javascript

JavaScript/TypeScript Proximity Pattern Examples

Examples demonstrating aggressive proximity patterns in JavaScript and TypeScript for AI-generated code.

📁 Examples

api-gateway.js

Complete API gateway with proximity patterns:

• 🧠 Circuit breaker with decision documentation
• ⚡ Performance monitoring and metrics
• 🛡️ Security considerations for DoS prevention
• 🎯 Tests colocated at bottom of file
• 🚨 Rich error context with recovery strategies

Key Pattern:

// 🧠 DECISION: 5-second timeout for upstream services
// Why: 99% of requests complete in 3s based on monitoring
// Buffer: 2s for network variability
// Alternative: 30s (rejected: too long, poor user experience)
const UPSTREAM_TIMEOUT_MS = 5000;

react-component.tsx

React component with colocation patterns:

• Component, styles, tests, and types together
• State management decisions
• Performance optimization documentation
• Error boundary reasoning

websocket-server.ts

WebSocket server with real-time patterns:

• Connection pooling decisions
• Heartbeat interval calculations
• Reconnection strategy documentation
• Message queue sizing

🎯 JavaScript-Specific Patterns

1. Constant Documentation

// 🧠 DECISION: 100-connection pool size
// Calculation: 1000 req/s × 0.1s response = 100 concurrent
// Alternative: 50 (rejected: exhaustion at peak)
const CONNECTION_POOL_SIZE = 100;

2. Class Method Decisions

class Cache {
  constructor() {
    // 🧠 DECISION: LRU eviction strategy
    // Why: Balances recency and frequency
    // Alternative: FIFO (rejected: ignores usage patterns)
    this.strategy = 'LRU';
  }
}

3. Error Context

// 🚨 ERROR: Circuit open, fail fast
// Recovery: Wait for timeout then retry
// User impact: 503 Service Unavailable
if (this.state === 'OPEN') {
  throw new Error(`Circuit open. Retry after ${this.nextAttempt}`);
}

🎯 TypeScript-Specific Patterns

1. Type Decisions

// 🧠 DECISION: Discriminated union for state machine
// Why: Compile-time exhaustiveness checking
// Alternative: Enum (rejected: less type safety)
type State = 
  | { type: 'idle' }
  | { type: 'loading'; startTime: number }
  | { type: 'error'; error: Error }
  | { type: 'success'; data: Data };

2. Generic Constraints

// 🧠 DECISION: Constrain T to serializable types
// Why: Prevent runtime serialization errors
// Alternative: any (rejected: no type safety)
function cache<T extends JsonSerializable>(key: string, value: T): void {
  localStorage.setItem(key, JSON.stringify(value));
}

3. Interface Documentation

interface RateLimiter {
  // 🧠 DECISION: Token bucket over fixed window
  // Why: Better burst handling
  // Benchmark: 30% fewer false positives
  algorithm: 'token-bucket';
  
  // ⚡ PERFORMANCE: 100 req/min rate
  // Measurement: P99 usage = 87 req/min
  tokensPerMinute: 100;
}

🚀 Running Examples

# JavaScript example
node api-gateway.js

# TypeScript example
npx ts-node websocket-server.ts

# Run tests (at bottom of files)
node api-gateway.js

# With performance profiling
node --inspect api-gateway.js

📊 Proximity Score: 91/100

These examples achieve high proximity scores:

• ✅ Every constant has decision documentation
• ✅ Tests colocated or in adjacent files
• ✅ Security threats and mitigations documented
• ✅ Performance choices include measurements
• ✅ Error handling with recovery strategies

💡 Component Colocation Pattern

feature/
├── UserProfile.tsx          # Component
├── UserProfile.test.tsx     # Tests (colocated)
├── UserProfile.styles.ts    # Styles (colocated)
├── UserProfile.types.ts     # Types (colocated)
└── useUserProfile.ts        # Hook (colocated)

🔗 References

• JavaScript Patterns Guide
• spiral-core - Inspiration