claude-autopm 2.8.2 → 2.8.4

package/packages/plugin-languages/scripts/examples/python-async-patterns.py

@@ -0,0 +1,289 @@
+#!/usr/bin/env python3
+"""
+Python Async Patterns - Context7 Best Practices
+
+Demonstrates modern Python async patterns from Context7 documentation:
+- AsyncIterator type hints
+- ParamSpec for type-safe decorators
+- TypeIs for type narrowing
+- TYPE_CHECKING for conditional imports
+
+Source: /python/cpython (19,631 snippets, trust 8.9)
+Source: /websites/fastapi_tiangolo (28,852 snippets, trust 9.0)
+"""
+
+import asyncio
+from typing import (
+    AsyncIterator,
+    Callable,
+    ParamSpec,
+    TypeVar,
+    TypeIs,
+    TYPE_CHECKING,
+)
+from collections.abc import Sequence
+
+# Conditional imports for type checking only (Context7 pattern)
+if TYPE_CHECKING:
+    from pydantic import BaseModel  # Only imported during type checking
+
+# Type variables for generic functions
+P = ParamSpec('P')
+R = TypeVar('R')
+T = TypeVar('T')
+
+
+# Context7 Pattern 1: AsyncIterator for async generators
+async def infinite_stream(start: int) -> AsyncIterator[int]:
+    """
+    Generate infinite stream of integers.
+
+    Context7 Best Practice: Use AsyncIterator type hint for async generators
+    Source: /python/cpython
+    """
+    current = start
+    while True:
+        yield current
+        current = await increment(current)
+
+
+async def increment(value: int) -> int:
+    """Async increment operation."""
+    await asyncio.sleep(0.01)  # Simulate async work
+    return value + 1
+
+
+async def take(n: int, ait: AsyncIterator[T]) -> list[T]:
+    """
+    Take n items from async iterator.
+
+    Context7 Pattern: Generic async iterator consumer
+    """
+    items = []
+    async for item in ait:
+        items.append(item)
+        if len(items) >= n:
+            break
+    return items
+
+
+# Context7 Pattern 2: ParamSpec for type-safe decorators
+def with_retry(
+    max_attempts: int = 3,
+    delay: float = 1.0
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    """
+    Decorator with retry logic - type-safe using ParamSpec.
+
+    Context7 Best Practice: Use ParamSpec for decorators that preserve signatures
+    Source: /python/cpython
+    """
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        async def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            last_exception = None
+            for attempt in range(max_attempts):
+                try:
+                    if asyncio.iscoroutinefunction(func):
+                        return await func(*args, **kwargs)
+                    return func(*args, **kwargs)
+                except Exception as e:
+                    last_exception = e
+                    if attempt < max_attempts - 1:
+                        await asyncio.sleep(delay * (attempt + 1))
+
+            raise last_exception
+
+        return wrapper  # type: ignore[return-value]
+
+    return decorator
+
+
+# Context7 Pattern 3: TypeIs for type narrowing
+def is_str_list(val: list[object]) -> TypeIs[list[str]]:
+    """
+    Type guard using TypeIs.
+
+    Context7 Best Practice: Use TypeIs for type narrowing in conditionals
+    Source: /python/cpython
+    """
+    return all(isinstance(x, str) for x in val)
+
+
+def process_strings(items: list[object]) -> list[str]:
+    """
+    Process list of items, ensuring they are strings.
+
+    Context7 Pattern: Type narrowing with TypeIs
+    """
+    if is_str_list(items):
+        # Type checker knows items is list[str] here
+        return [s.upper() for s in items]
+
+    raise TypeError("All items must be strings")
+
+
+# FastAPI Async Patterns (Context7 verified)
+class DataProcessor:
+    """
+    Demonstrates FastAPI async patterns.
+
+    Context7 Source: /websites/fastapi_tiangolo
+    """
+
+    @with_retry(max_attempts=3, delay=0.5)
+    async def fetch_data(self, url: str) -> dict:
+        """
+        Fetch data with retry logic.
+
+        Context7 Pattern: Async methods with decorators
+        """
+        # Simulate API call
+        await asyncio.sleep(0.1)
+        return {"url": url, "data": "sample"}
+
+    async def process_batch(
+        self,
+        items: Sequence[str]
+    ) -> AsyncIterator[dict]:
+        """
+        Process items in batch, yielding results.
+
+        Context7 Pattern: AsyncIterator for streaming results
+        """
+        for item in items:
+            result = await self.fetch_data(item)
+            await asyncio.sleep(0.05)
+            yield result
+
+    async def aggregate_results(
+        self,
+        items: Sequence[str]
+    ) -> list[dict]:
+        """
+        Aggregate all results from async iterator.
+
+        Context7 Pattern: Consuming async iterators
+        """
+        results = []
+        async for result in self.process_batch(items):
+            results.append(result)
+        return results
+
+
+# Example usage with type safety
+async def main() -> None:
+    """Demonstrate all Context7 patterns."""
+
+    # Pattern 1: AsyncIterator
+    print("Pattern 1: AsyncIterator")
+    stream = infinite_stream(1)
+    first_five = await take(5, stream)
+    print(f"First 5 from stream: {first_five}")
+
+    # Pattern 2: ParamSpec decorator
+    print("\nPattern 2: ParamSpec Decorator")
+    processor = DataProcessor()
+    result = await processor.fetch_data("https://api.example.com/data")
+    print(f"Fetched: {result}")
+
+    # Pattern 3: TypeIs type narrowing
+    print("\nPattern 3: TypeIs Type Narrowing")
+    mixed_list: list[object] = ["hello", "world"]
+    try:
+        processed = process_strings(mixed_list)
+        print(f"Processed strings: {processed}")
+    except TypeError as e:
+        print(f"Type error: {e}")
+
+    # FastAPI async patterns
+    print("\nFastAPI Async Patterns")
+    items = ["item1", "item2", "item3"]
+
+    # Streaming results
+    print("Streaming results:")
+    async for result in processor.process_batch(items):
+        print(f"  Processed: {result}")
+
+    # Aggregated results
+    all_results = await processor.aggregate_results(items)
+    print(f"All results: {len(all_results)} items")
+
+
+if __name__ == "__main__":
+    # Run async main
+    asyncio.run(main())
+
+
+# Additional Context7 Best Practices
+
+# 1. Type hints for all functions (MANDATORY)
+def typed_function(param: str, count: int = 1) -> list[str]:
+    """All functions must have type hints."""
+    return [param] * count
+
+
+# 2. Use modern type syntax (list[T] not List[T])
+def modern_types(items: list[str], mapping: dict[str, int]) -> set[str]:
+    """Use built-in generics (Python 3.9+)."""
+    return set(items)
+
+
+# 3. Async context managers for resource cleanup
+class AsyncResource:
+    """Context7 Pattern: Async context manager."""
+
+    async def __aenter__(self) -> 'AsyncResource':
+        """Acquire resource."""
+        await asyncio.sleep(0.01)
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        """Release resource."""
+        await asyncio.sleep(0.01)
+
+
+async def use_resource() -> None:
+    """Demonstrate async context manager."""
+    async with AsyncResource() as resource:
+        print("Using resource")
+
+
+# 4. Dataclasses for structured data
+from dataclasses import dataclass
+
+
+@dataclass
+class User:
+    """Context7 Pattern: Dataclasses for data models."""
+    id: int
+    email: str
+    username: str
+    active: bool = True
+
+
+# 5. Pydantic for validation (when FastAPI is used)
+# This would normally import from pydantic, but we use TYPE_CHECKING
+if TYPE_CHECKING:
+    class UserCreate(BaseModel):
+        """User creation schema with validation."""
+        email: str  # Would use EmailStr from pydantic
+        username: str
+        password: str  # Would use SecretStr from pydantic
+
+
+print("""
+Context7 Verified Best Practices Applied:
+==========================================
+1. ✅ AsyncIterator type hints for async generators
+2. ✅ ParamSpec for type-safe decorators
+3. ✅ TypeIs for type narrowing
+4. ✅ TYPE_CHECKING for conditional imports
+5. ✅ Modern type syntax (list[T] not List[T])
+6. ✅ Async context managers
+7. ✅ Dataclasses for data models
+8. ✅ Comprehensive type hints
+
+Sources:
+- /python/cpython (19,631 snippets, trust 8.9)
+- /websites/fastapi_tiangolo (28,852 snippets, trust 9.0)
+""")

package/packages/plugin-languages/scripts/examples/typescript-patterns.ts

@@ -0,0 +1,432 @@
+#!/usr/bin/env tsx
+/**
+ * TypeScript Patterns - Context7 Best Practices
+ *
+ * Demonstrates modern TypeScript patterns for Node.js backend:
+ * - Type-safe API client with generics
+ * - Discriminated unions for type safety
+ * - Utility types for transformation
+ * - Decorators for cross-cutting concerns
+ * - Async patterns with proper typing
+ *
+ * Combines patterns from:
+ * - /nodejs/node (Node.js async patterns)
+ * - /airbnb/javascript (ES6 best practices)
+ */
+
+// Type-safe API Response with Generics
+interface ApiResponse<T> {
+  status: number;
+  data: T;
+  error?: string;
+  timestamp: Date;
+}
+
+// Discriminated Unions for Type Safety
+type Result<T, E = Error> =
+  | { success: true; value: T }
+  | { success: false; error: E };
+
+// Utility Type Examples
+type User = {
+  id: number;
+  email: string;
+  username: string;
+  password: string;
+  createdAt: Date;
+};
+
+// ✅ CORRECT: Use Omit to exclude password from public user
+type PublicUser = Omit<User, 'password'>;
+
+// ✅ CORRECT: Use Pick to select specific fields
+type UserCredentials = Pick<User, 'email' | 'password'>;
+
+// ✅ CORRECT: Use Partial for update operations
+type UserUpdate = Partial<Omit<User, 'id' | 'createdAt'>>;
+
+// ✅ CORRECT: Use Required to enforce all fields
+type CompleteUser = Required<User>;
+
+// Type-Safe API Client
+class ApiClient {
+  constructor(
+    private baseURL: string,
+    private timeout: number = 5000
+  ) {}
+
+  // Generic method with proper typing
+  async get<T>(endpoint: string): Promise<Result<T, string>> {
+    try {
+      // Simulate API call with AbortSignal (Node.js pattern)
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+
+      try {
+        // In real implementation, use fetch with signal
+        await this.delay(100);
+        clearTimeout(timeoutId);
+
+        const data = { example: 'data' } as unknown as T;
+
+        return {
+          success: true,
+          value: data,
+        };
+      } catch (error) {
+        clearTimeout(timeoutId);
+        throw error;
+      }
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  async post<T, D>(
+    endpoint: string,
+    data: D
+  ): Promise<Result<T, string>> {
+    try {
+      await this.delay(100);
+      const result = data as unknown as T;
+
+      return {
+        success: true,
+        value: result,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  private delay(ms: number): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+}
+
+// Type-Safe Repository Pattern
+interface Repository<T> {
+  findById(id: number): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  create(data: Omit<T, 'id'>): Promise<T>;
+  update(id: number, data: Partial<T>): Promise<T>;
+  delete(id: number): Promise<void>;
+}
+
+class UserRepository implements Repository<User> {
+  private users: Map<number, User> = new Map();
+  private nextId = 1;
+
+  async findById(id: number): Promise<User | null> {
+    return this.users.get(id) ?? null;
+  }
+
+  async findAll(): Promise<User[]> {
+    return Array.from(this.users.values());
+  }
+
+  async create(data: Omit<User, 'id'>): Promise<User> {
+    const user: User = {
+      id: this.nextId++,
+      ...data,
+    };
+    this.users.set(user.id, user);
+    return user;
+  }
+
+  async update(id: number, data: Partial<User>): Promise<User> {
+    const existing = this.users.get(id);
+    if (!existing) {
+      throw new Error(`User ${id} not found`);
+    }
+
+    const updated = { ...existing, ...data };
+    this.users.set(id, updated);
+    return updated;
+  }
+
+  async delete(id: number): Promise<void> {
+    this.users.delete(id);
+  }
+}
+
+// Service Layer with Type Safety
+class UserService {
+  constructor(
+    private repository: UserRepository,
+    private apiClient: ApiClient
+  ) {}
+
+  async createUser(
+    credentials: UserCredentials
+  ): Promise<Result<PublicUser, string>> {
+    try {
+      // Validate email format
+      if (!this.isValidEmail(credentials.email)) {
+        return {
+          success: false,
+          error: 'Invalid email format',
+        };
+      }
+
+      // Hash password (simplified)
+      const hashedPassword = await this.hashPassword(credentials.password);
+
+      // Create user
+      const user = await this.repository.create({
+        ...credentials,
+        password: hashedPassword,
+        username: credentials.email.split('@')[0],
+        createdAt: new Date(),
+      });
+
+      // Return public user (without password)
+      const publicUser = this.toPublicUser(user);
+
+      return {
+        success: true,
+        value: publicUser,
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  async getUser(id: number): Promise<Result<PublicUser, string>> {
+    const user = await this.repository.findById(id);
+
+    if (!user) {
+      return {
+        success: false,
+        error: `User ${id} not found`,
+      };
+    }
+
+    return {
+      success: true,
+      value: this.toPublicUser(user),
+    };
+  }
+
+  async updateUser(
+    id: number,
+    update: UserUpdate
+  ): Promise<Result<PublicUser, string>> {
+    try {
+      const updated = await this.repository.update(id, update);
+
+      return {
+        success: true,
+        value: this.toPublicUser(updated),
+      };
+    } catch (error) {
+      return {
+        success: false,
+        error: error instanceof Error ? error.message : 'Unknown error',
+      };
+    }
+  }
+
+  // Type guard
+  private isValidEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+
+  private async hashPassword(password: string): Promise<string> {
+    // Simplified hashing
+    return `hashed_${password}`;
+  }
+
+  // Type transformation helper
+  private toPublicUser(user: User): PublicUser {
+    // ✅ CORRECT: Use destructuring with rest to omit password
+    const { password, ...publicUser } = user;
+    return publicUser;
+  }
+}
+
+// Async Iterator with TypeScript (Node.js pattern)
+class AsyncDataProcessor<T> {
+  constructor(private items: T[]) {}
+
+  // ✅ CORRECT: Properly typed async generator
+  async *process(): AsyncIterableIterator<T> {
+    for (const item of this.items) {
+      // Simulate async processing
+      await new Promise((resolve) => setTimeout(resolve, 100));
+      yield item;
+    }
+  }
+
+  async collect(): Promise<T[]> {
+    const results: T[] = [];
+
+    // ✅ CORRECT: for await...of with proper typing
+    for await (const item of this.process()) {
+      results.push(item);
+    }
+
+    return results;
+  }
+}
+
+// Type-Safe Event Emitter
+type EventMap = {
+  userCreated: (user: PublicUser) => void;
+  userUpdated: (id: number, updates: UserUpdate) => void;
+  userDeleted: (id: number) => void;
+};
+
+class TypedEventEmitter {
+  private handlers: Map<keyof EventMap, Set<Function>> = new Map();
+
+  on<K extends keyof EventMap>(event: K, handler: EventMap[K]): void {
+    if (!this.handlers.has(event)) {
+      this.handlers.set(event, new Set());
+    }
+    this.handlers.get(event)!.add(handler);
+  }
+
+  emit<K extends keyof EventMap>(
+    event: K,
+    ...args: Parameters<EventMap[K]>
+  ): void {
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      handlers.forEach((handler) => handler(...args));
+    }
+  }
+
+  off<K extends keyof EventMap>(event: K, handler: EventMap[K]): void {
+    const handlers = this.handlers.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+    }
+  }
+}
+
+// Demo Application
+async function main() {
+  console.log('TypeScript Patterns - Context7 Best Practices');
+  console.log('='.repeat(60));
+
+  // Initialize services
+  const repository = new UserRepository();
+  const apiClient = new ApiClient('https://api.example.com');
+  const userService = new UserService(repository, apiClient);
+  const eventEmitter = new TypedEventEmitter();
+
+  // Setup event handlers
+  eventEmitter.on('userCreated', (user) => {
+    console.log(`\n[Event] User created: ${user.username} (${user.email})`);
+  });
+
+  eventEmitter.on('userUpdated', (id, updates) => {
+    console.log(`\n[Event] User ${id} updated:`, updates);
+  });
+
+  // Pattern 1: Creating User with Type Safety
+  console.log('\nPattern 1: Create User with Type Safety');
+  const createResult = await userService.createUser({
+    email: 'alice@example.com',
+    password: 'securepass123',
+  });
+
+  if (createResult.success) {
+    console.log('Created user:', createResult.value);
+    eventEmitter.emit('userCreated', createResult.value);
+  } else {
+    console.error('Failed to create user:', createResult.error);
+  }
+
+  // Pattern 2: Type-Safe Updates with Partial
+  console.log('\nPattern 2: Type-Safe Updates');
+  if (createResult.success) {
+    const updateResult = await userService.updateUser(createResult.value.id, {
+      username: 'alice_smith',
+      email: 'alice.smith@example.com',
+    });
+
+    if (updateResult.success) {
+      console.log('Updated user:', updateResult.value);
+      eventEmitter.emit('userUpdated', updateResult.value.id, {
+        username: 'alice_smith',
+      });
+    }
+  }
+
+  // Pattern 3: Async Iterator with TypeScript
+  console.log('\nPattern 3: Async Iterator Processing');
+  const processor = new AsyncDataProcessor([1, 2, 3, 4, 5]);
+
+  console.log('Processing items...');
+  for await (const item of processor.process()) {
+    console.log(`  Processed: ${item}`);
+  }
+
+  // Pattern 4: Generic API Client
+  console.log('\nPattern 4: Generic API Client');
+  type TodoItem = { id: number; title: string; completed: boolean };
+
+  const todoResult = await apiClient.get<TodoItem[]>('/todos');
+
+  if (todoResult.success) {
+    console.log('Fetched todos:', todoResult.value);
+  } else {
+    console.error('Failed to fetch todos:', todoResult.error);
+  }
+
+  // Pattern 5: Result Type Pattern
+  console.log('\nPattern 5: Result Type Pattern');
+  const users = await repository.findAll();
+  console.log(`Total users in repository: ${users.length}`);
+
+  users.forEach((user) => {
+    const publicUser: PublicUser = {
+      id: user.id,
+      email: user.email,
+      username: user.username,
+      createdAt: user.createdAt,
+    };
+    console.log(`  - ${publicUser.username} (${publicUser.email})`);
+  });
+
+  console.log(`
+Context7 Verified TypeScript Patterns:
+======================================
+1. ✅ Generic types for reusable components
+2. ✅ Discriminated unions for type-safe error handling
+3. ✅ Utility types (Omit, Pick, Partial, Required)
+4. ✅ Type guards and type narrowing
+5. ✅ Async iterators with proper typing
+6. ✅ Type-safe event emitters
+7. ✅ Repository pattern with generics
+8. ✅ Service layer with error handling
+9. ✅ Result type pattern for operations
+10. ✅ Proper async/await typing
+
+Sources:
+- /nodejs/node (async patterns with typing)
+- /airbnb/javascript (ES6 patterns with TypeScript)
+
+Type Safety Benefits:
+- Compile-time error detection
+- IDE autocomplete and IntelliSense
+- Refactoring confidence
+- Self-documenting code
+- Reduced runtime errors
+`);
+}
+
+// Run the demo
+main().catch(console.error);