@fjell/registry 4.4.7 → 4.4.10

package/docs/public/TIMING_NODE_OPTIMIZATION.md

@@ -0,0 +1,207 @@
+# Node.js Optimization for Timing Tests
+
+This document outlines Node.js runtime parameters that can be tuned to minimize interference and improve timing test accuracy.
+
+## Quick Start: Optimized Timing Test
+
+```bash
+pnpm run test:timing:optimized
+```
+
+This runs timing tests with pre-configured optimal Node.js flags.
+
+## Key Node.js Optimization Flags
+
+### Memory Management
+
+#### `--max-old-space-size=8192`
+- **Purpose**: Increases maximum heap size to 8GB (default ~1.4GB)
+- **Benefit**: Prevents garbage collection during test runs
+- **Why 8GB**: Provides ample headroom for 100 rounds × multiple tree sizes
+- **Alternative**: `--max-old-space-size=4096` for systems with less RAM
+
+#### `--max-semi-space-size=1024`
+- **Purpose**: Increases semi-space size to 1GB (default varies)
+- **Benefit**: Reduces minor GC frequency during object allocation
+- **Impact**: Each semi-space can hold more objects before collection
+
+### Garbage Collection Control
+
+#### `--expose-gc`
+- **Purpose**: Exposes `global.gc()` function for manual garbage collection
+- **Benefit**: Allows forced GC between test rounds for consistent baselines
+- **Usage**: Can trigger GC at specific points to isolate timing measurements
+
+#### `--gc-interval=1000000`
+- **Purpose**: Reduces GC frequency (higher number = less frequent)
+- **Benefit**: Minimizes GC interruptions during timing measurements
+- **Trade-off**: Uses more memory but provides consistent timing
+
+### Execution Predictability
+
+#### `--predictable`
+- **Purpose**: Makes execution more deterministic
+- **Benefit**: Reduces timing variance from non-deterministic optimizations
+- **Impact**: Slightly slower but more consistent measurements
+
+#### `--no-compilation-cache`
+- **Purpose**: Disables V8 compilation cache
+- **Benefit**: Ensures consistent JIT compilation behavior across runs
+- **Use Case**: When testing cold start performance or eliminating cache effects
+
+### JIT Compilation Control
+
+#### `--optimize-for-size`
+- **Purpose**: Optimizes for code size rather than speed
+- **Benefit**: More predictable compilation behavior
+- **Alternative**: `--max-opt` for maximum optimization (less predictable)
+
+#### `--no-opt`
+- **Purpose**: Disables JIT compilation entirely
+- **Benefit**: Eliminates JIT timing variance (but much slower execution)
+- **Use Case**: Testing interpreter-only performance
+
+## Complete Optimization Command
+
+For maximum timing accuracy, use all optimization flags:
+
+```bash
+# Use NODE_OPTIONS for compatibility with modern Node.js
+NODE_OPTIONS="--max-old-space-size=8192 --max-semi-space-size=1024" \
+vitest run tests/timing.test.ts
+
+# Or use direct node invocation (requires vitest executable)
+node --max-old-space-size=8192 --max-semi-space-size=1024 \
+./node_modules/vitest/vitest.mjs run tests/timing.test.ts
+```
+
+## System-Specific Adjustments
+
+### Low-Memory Systems (< 8GB RAM)
+```bash
+NODE_OPTIONS="--max-old-space-size=2048 --max-semi-space-size=256" \
+vitest run tests/timing.test.ts
+```
+
+### High-Memory Systems (> 16GB RAM)
+```bash
+NODE_OPTIONS="--max-old-space-size=16384 --max-semi-space-size=2048" \
+vitest run tests/timing.test.ts
+```
+
+### Docker/Container Environments
+```bash
+NODE_OPTIONS="--max-old-space-size=4096 --max-semi-space-size=512" \
+vitest run tests/timing.test.ts
+```
+
+## Environment Variables
+
+### Additional V8 Options
+```bash
+export NODE_OPTIONS="--max-old-space-size=8192 --max-semi-space-size=1024"
+```
+
+### Memory Monitoring
+```bash
+export NODE_ENV=production  # Disable development overhead
+export UV_THREADPOOL_SIZE=8  # Increase thread pool if needed
+```
+
+## Monitoring Memory During Tests
+
+Add memory monitoring to timing tests:
+
+```typescript
+// Add to timing test setup
+if (global.gc) {
+  console.log('Memory before tests:', process.memoryUsage());
+  global.gc();
+}
+
+// Add between test rounds
+if (global.gc && round % 20 === 0) {
+  global.gc();
+  console.log(`Memory after round ${round}:`, process.memoryUsage());
+}
+```
+
+## Platform-Specific Considerations
+
+### macOS
+- Default memory limits are generous
+- Use `--max-old-space-size=8192` safely
+- Activity Monitor shows Node.js memory usage
+
+### Linux
+- Check `ulimit -v` for virtual memory limits
+- May need `sudo sysctl vm.max_map_count=262144` for large heaps
+- Use `htop` or `ps` to monitor memory
+
+### Windows
+- WSL may have memory constraints
+- PowerShell: `Get-Process node | Select-Object WorkingSet64`
+- Task Manager shows detailed memory breakdown
+
+### CI/CD Environments
+- GitHub Actions: 7GB RAM limit, use `--max-old-space-size=4096`
+- GitLab CI: Variable memory, check runner specs
+- Docker: Set container memory limits appropriately
+
+## Performance Analysis Tools
+
+### V8 Profiling
+```bash
+node --prof --log-timer-events ./timing-test.js
+```
+
+### Heap Snapshots
+```bash
+node --inspect --heap-prof ./timing-test.js
+```
+
+### GC Logging
+```bash
+node --trace-gc --trace-gc-verbose ./timing-test.js
+```
+
+## Validation
+
+Test that optimizations are working:
+
+```bash
+# Run normal timing tests
+pnpm run test:timing
+
+# Run optimized timing tests
+pnpm run test:timing:optimized
+
+# Compare results - optimized should show:
+# 1. Lower timing variance (smaller standard deviations)
+# 2. More consistent Bollinger bands
+# 3. Fewer outlier measurements
+# 4. Reduced memory-related timing spikes
+```
+
+## Recommended Configuration
+
+For most use cases, the optimized configuration provides the best balance:
+
+```json
+{
+  "scripts": {
+    "test:timing:optimized": "NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=1024\" vitest run tests/timing.test.ts"
+  }
+}
+```
+
+This configuration:
+- ✅ Eliminates most GC interference
+- ✅ Provides consistent execution
+- ✅ Works on most development machines
+- ✅ Maintains reasonable test execution time
+- ✅ Produces reliable performance metrics
+
+---
+
+*For production timing analysis, always use optimized Node.js flags to ensure accurate performance measurements.*

package/docs/public/examples/coordinates-example.ts

@@ -0,0 +1,253 @@
+/**
+ * Coordinates Discovery Example
+ *
+ * This example demonstrates how to use the getCoordinates() method to:
+ * - Discover all registered instances in a registry
+ * - Inspect coordinates and their scopes
+ * - Monitor registry state for debugging
+ * - Implement discovery mechanisms
+ *
+ * Run this example with: npx tsx examples/coordinates-example.ts
+ *
+ * Note: In a real application, import from the built package:
+ * import { createRegistry, createInstance } from '@fjell/registry';
+ */
+
+// Import the actual registry functionality
+import { createRegistry } from '../src/Registry';
+import { createInstance } from '../src/Instance';
+
+// ===== Service Examples =====
+
+class DatabaseService {
+  constructor(private type: string, private environment: string) { }
+
+  connect() {
+    console.log(`Connected to ${this.type} database in ${this.environment}`);
+  }
+
+  getInfo() {
+    return `${this.type} (${this.environment})`;
+  }
+}
+
+class CacheService {
+  constructor(private type: string) { }
+
+  get(key: string) {
+    console.log(`Getting ${key} from ${this.type} cache`);
+    return `cached_${key}`;
+  }
+
+  getInfo() {
+    return this.type;
+  }
+}
+
+class LoggingService {
+  constructor(private level: string) { }
+
+  log(message: string) {
+    console.log(`[${this.level.toUpperCase()}] ${message}`);
+  }
+
+  getInfo() {
+    return `Logging at ${this.level} level`;
+  }
+}
+
+// ===== Main Example =====
+
+async function runCoordinatesExample() {
+  console.log('🔍 Registry Coordinates Discovery Example\n');
+
+  // Step 1: Create a registry
+  console.log('1. Creating registry...');
+  const registry = createRegistry('services');
+  console.log('   ✅ Registry created\n');
+
+  // Step 2: Register multiple instances with different scopes
+  console.log('2. Registering instances with various configurations...\n');
+
+  // Database services for different environments
+  registry.createInstance(
+    ['database'],
+    ['production', 'postgres'],
+    (coordinate, context) => {
+      const service = new DatabaseService('PostgreSQL', 'production');
+      const instance = createInstance(context.registry, coordinate);
+      (instance as any).connect = service.connect.bind(service);
+      (instance as any).getInfo = service.getInfo.bind(service);
+      return instance;
+    }
+  );
+  console.log('   ✅ PostgreSQL database (production) registered');
+
+  registry.createInstance(
+    ['database'],
+    ['development', 'sqlite'],
+    (coordinate, context) => {
+      const service = new DatabaseService('SQLite', 'development');
+      const instance = createInstance(context.registry, coordinate);
+      (instance as any).connect = service.connect.bind(service);
+      (instance as any).getInfo = service.getInfo.bind(service);
+      return instance;
+    }
+  );
+  console.log('   ✅ SQLite database (development) registered');
+
+  // Cache services
+  registry.createInstance(
+    ['cache', 'redis'],
+    ['production'],
+    (coordinate, context) => {
+      const service = new CacheService('Redis');
+      const instance = createInstance(context.registry, coordinate);
+      (instance as any).get = service.get.bind(service);
+      (instance as any).getInfo = service.getInfo.bind(service);
+      return instance;
+    }
+  );
+  console.log('   ✅ Redis cache (production) registered');
+
+  registry.createInstance(
+    ['cache', 'memory'],
+    ['development', 'testing'],
+    (coordinate, context) => {
+      const service = new CacheService('In-Memory');
+      const instance = createInstance(context.registry, coordinate);
+      (instance as any).get = service.get.bind(service);
+      (instance as any).getInfo = service.getInfo.bind(service);
+      return instance;
+    }
+  );
+  console.log('   ✅ Memory cache (development/testing) registered');
+
+  // Logging services
+  registry.createInstance(
+    ['logging'],
+    ['production'],
+    (coordinate, context) => {
+      const service = new LoggingService('error');
+      const instance = createInstance(context.registry, coordinate);
+      (instance as any).log = service.log.bind(service);
+      (instance as any).getInfo = service.getInfo.bind(service);
+      return instance;
+    }
+  );
+  console.log('   ✅ Error logging (production) registered');
+
+  registry.createInstance(
+    ['logging'],
+    ['development'],
+    (coordinate, context) => {
+      const service = new LoggingService('debug');
+      const instance = createInstance(context.registry, coordinate);
+      (instance as any).log = service.log.bind(service);
+      (instance as any).getInfo = service.getInfo.bind(service);
+      return instance;
+    }
+  );
+  console.log('   ✅ Debug logging (development) registered\n');
+
+  // Step 3: Demonstrate getCoordinates functionality
+  console.log('3. Discovering all registered coordinates...\n');
+
+  const coordinates = registry.getCoordinates();
+  console.log(`📊 Total registered coordinates: ${coordinates.length}\n`);
+
+  // Display all coordinates with their details
+  console.log('📍 Registered Coordinates:');
+  console.log('─'.repeat(60));
+  coordinates.forEach((coord, index) => {
+    console.log(`${index + 1}. ${coord.toString()}`);
+    console.log(`   Key Path: [${coord.kta.join(' → ')}]`);
+    console.log(`   Scopes: ${coord.scopes.length > 0 ? coord.scopes.join(', ') : 'none'}`);
+    console.log('');
+  });
+
+  // Step 4: Demonstrate filtering and analysis
+  console.log('4. Analyzing coordinate patterns...\n');
+
+  // Group by environment
+  const byEnvironment = {
+    production: coordinates.filter(c => c.scopes.includes('production')),
+    development: coordinates.filter(c => c.scopes.includes('development')),
+    testing: coordinates.filter(c => c.scopes.includes('testing')),
+    unscoped: coordinates.filter(c => c.scopes.length === 0)
+  };
+
+  console.log('🏢 Coordinates by Environment:');
+  Object.entries(byEnvironment).forEach(([env, coords]) => {
+    if (coords.length > 0) {
+      console.log(`   ${env}: ${coords.length} instance(s)`);
+      coords.forEach(coord => {
+        console.log(`     - ${coord.kta.join('.')}`);
+      });
+    }
+  });
+
+  // Group by service type (first element of kta)
+  const byServiceType = coordinates.reduce((acc, coord) => {
+    const serviceType = coord.kta[0];
+    if (!acc[serviceType]) acc[serviceType] = [];
+    acc[serviceType].push(coord);
+    return acc;
+  }, {} as Record<string, typeof coordinates>);
+
+  console.log('\n🔧 Coordinates by Service Type:');
+  Object.entries(byServiceType).forEach(([type, coords]) => {
+    console.log(`   ${type}: ${coords.length} instance(s)`);
+    coords.forEach(coord => {
+      const scopeInfo = coord.scopes.length > 0 ? ` (${coord.scopes.join(', ')})` : '';
+      console.log(`     - ${coord.kta.join('.')}${scopeInfo}`);
+    });
+  });
+
+  // Step 5: Demonstrate practical usage scenarios
+  console.log('\n5. Practical usage scenarios...\n');
+
+  // Scenario 1: Health check - verify all expected services are registered
+  console.log('🏥 Health Check Example:');
+  const expectedServices = ['database', 'cache', 'logging'];
+  const registeredServices = [...new Set(coordinates.map(c => c.kta[0]))];
+
+  expectedServices.forEach(service => {
+    const isRegistered = registeredServices.includes(service);
+    console.log(`   ${service}: ${isRegistered ? '✅ Registered' : '❌ Missing'}`);
+  });
+
+  // Scenario 2: Environment validation
+  console.log('\n🌍 Environment Validation:');
+  const productionServices = coordinates.filter(c => c.scopes.includes('production'));
+  const developmentServices = coordinates.filter(c => c.scopes.includes('development'));
+
+  console.log(`   Production environment has ${productionServices.length} service(s) registered`);
+  console.log(`   Development environment has ${developmentServices.length} service(s) registered`);
+
+  // Scenario 3: Discovery mechanism
+  console.log('\n🔍 Service Discovery Example:');
+  console.log('   Available cache services:');
+  coordinates
+    .filter(c => c.kta.includes('cache'))
+    .forEach(coord => {
+      console.log(`     - ${coord.kta.join('.')} (${coord.scopes.join(', ') || 'any scope'})`);
+    });
+
+  console.log('\n✨ Coordinates discovery example completed!');
+
+  return {
+    totalCoordinates: coordinates.length,
+    coordinates: coordinates,
+    byEnvironment,
+    byServiceType
+  };
+}
+
+// Export for testing
+export { runCoordinatesExample };
+
+// Run the example if this file is executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runCoordinatesExample().catch(console.error);
+}