@fjell/registry 4.4.51 → 4.4.53

package/docs/public/TIMING_NODE_OPTIMIZATION.md

@@ -1,207 +0,0 @@
-# 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
-npm run test:timing
-
-# Run optimized timing tests
-npm 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/api.md

@@ -1,62 +0,0 @@
-# API Reference
-
-Complete Registry API documentation and method reference.
-
-## Core Registry Interface
-
-```typescript
-interface Registry {
-  readonly type: string; // Mandatory type identifier
-  createInstance: <...>(...) => Instance<...>;
-  get: (...) => Instance | null;
-  getCoordinates: () => Coordinate[]; // Discover all registered coordinates
-  instanceTree: InstanceTree;
-}
-```
-
-## Primary Methods
-
-### `createRegistry(type: string): Registry`
-Creates a new registry with the specified type identifier.
-
-### `registry.createInstance(kta, scopes, factory)`
-Registers a new service instance with the given key type array and scopes.
-
-### `registry.get(kta, options)`
-Retrieves a service instance by key type array and scope options.
-
-### `registry.getCoordinates(): Coordinate[]`
-Returns all registered coordinates for service discovery and introspection.
-
-## RegistryHub Interface
-
-```typescript
-interface RegistryHub {
-  registerRegistry: (registry: Registry) => void;
-  get: (registryType: string, kta: string[], options?: GetOptions) => Instance | null;
-  getRegistries: () => Registry[];
-  getAllCoordinates: () => Array<{coordinate: Coordinate, registryType: string}>;
-}
-```
-
-## Coordinate System
-
-```typescript
-interface Coordinate {
-  kta: string[]; // Key Type Array - hierarchical identifiers
-  scopes: string[]; // Context qualifiers
-}
-```
-
-## Complete Documentation
-
-For comprehensive API documentation with detailed examples, implementation patterns, and advanced usage scenarios, see the **Foundation** section which contains the complete Registry documentation including:
-
-- Interface definitions and type signatures
-- Detailed method documentation with examples
-- Registry and RegistryHub patterns
-- Coordinate system explanation
-- Service discovery and introspection
-- Error handling and best practices
-
-The Foundation section serves as the authoritative API reference with full context and examples.

package/docs/public/client-api-overview.md

@@ -1,137 +0,0 @@
-# Client API Documentation
-
-Welcome to the comprehensive Client API documentation for the Fjell ecosystem. This section provides complete guidance for building resilient, production-ready applications with advanced error handling and retry logic.
-
-## What's New
-
-The Client API now includes enterprise-grade error handling and resilience features:
-
-- **🔄 Automatic Retry Logic** - Exponential backoff with jitter for transient failures
-- **🎯 Custom Error Types** - 10+ specific error classes for different scenarios
-- **🛡️ Production Resilience** - Circuit breakers, graceful degradation, monitoring integration
-- **⚙️ Flexible Configuration** - Environment-aware settings for dev, staging, and production
-- **📊 Comprehensive Monitoring** - Error tracking, metrics, and alerting integration
-
-## Documentation Sections
-
-### Operations
-Complete guides for all API operations with examples, error handling, and best practices:
-
-- **[Operations Overview](./operations/README.md)** - Complete guide to all available operations
-- **[All Operation](./operations/all.md)** - Retrieve multiple items with queries, pagination, and filtering
-- **[Create Operation](./operations/create.md)** - Create new items with validation and batch operations
-- **[Get Operation](./operations/get.md)** - Retrieve single items by key with caching strategies
-
-### Error Handling & Resilience
-Advanced error handling for production environments:
-
-- **[Error Handling Overview](./error-handling/README.md)** - Comprehensive error handling system
-- **[Network Errors](./error-handling/network-errors.md)** - Handle connection failures and timeouts
-
-### Configuration
-Complete setup and configuration guide:
-
-- **[Configuration Guide](./configuration.md)** - API setup, authentication, and environment configuration
-
-## Quick Start
-
-### Basic Setup
-
-```typescript
-import { createPItemApi } from '@fjell/client-api';
-
-const userApi = createPItemApi<User, 'user'>('user', ['users'], {
-  baseUrl: 'https://api.example.com',
-  enableErrorHandling: true,
-  retryConfig: {
-    maxRetries: 3,
-    initialDelayMs: 1000,
-    maxDelayMs: 30000,
-    backoffMultiplier: 2,
-    enableJitter: true
-  }
-});
-```
-
-### With Error Handling
-
-```typescript
-try {
-  const user = await userApi.create({
-    name: 'John Doe',
-    email: 'john@example.com'
-  });
-
-  console.log('User created:', user.id);
-} catch (error) {
-  if (error.code === 'VALIDATION_ERROR') {
-    // Handle validation errors
-    error.validationErrors.forEach(err => {
-      console.log(`${err.field}: ${err.message}`);
-    });
-  } else if (error.code === 'NETWORK_ERROR') {
-    // Network errors are automatically retried
-    console.log('Network issue resolved or exhausted retries');
-  }
-}
-```
-
-## Key Features
-
-### Error Types Handled
-
-| Error Type | Code | Retryable | Description |
-|------------|------|-----------|-------------|
-| **NetworkError** | `NETWORK_ERROR` | ✅ | Connection failures, DNS issues |
-| **TimeoutError** | `TIMEOUT_ERROR` | ✅ | Request timeouts |
-| **ServerError** | `SERVER_ERROR` | ✅ | 5xx HTTP status codes |
-| **RateLimitError** | `RATE_LIMIT_ERROR` | ✅ | 429 Too Many Requests |
-| **AuthenticationError** | `AUTHENTICATION_ERROR` | ❌ | 401 Unauthorized |
-| **ValidationError** | `VALIDATION_ERROR` | ❌ | 400 Bad Request |
-| **NotFoundError** | `NOT_FOUND_ERROR` | ❌ | 404 Not Found |
-
-### Production Configuration
-
-```typescript
-const productionConfig = {
-  baseUrl: 'https://api.example.com',
-  retryConfig: {
-    maxRetries: 5,
-    initialDelayMs: 1000,
-    maxDelayMs: 60000,
-    backoffMultiplier: 1.5,
-    enableJitter: true
-  },
-  errorHandler: (error, context) => {
-    // Send to monitoring service
-    monitoring.recordError(error, context);
-
-    // Business-specific error handling
-    if (error.code === 'PAYMENT_FAILED') {
-      notificationService.sendPaymentFailure(context.customerId);
-    }
-  }
-};
-```
-
-## Examples
-
-See the [Examples](../examples-README.md) section for complete usage scenarios including:
-
-- Simple API operations with error handling
-- Enterprise e-commerce platform patterns
-- Comprehensive error handling demonstrations
-- Production configuration examples
-
-## Support
-
-For additional help:
-
-- Review the detailed operation guides in the Operations section
-- Check the Error Handling section for resilience patterns
-- Explore the Configuration guide for setup options
-- See the Examples for complete working code
-
----
-
-*Built with comprehensive error handling and production resilience in mind.*