@fjell/registry 4.4.52 → 4.4.54

package/examples/README.md

@@ -1,241 +0,0 @@
-# Registry Examples
-
-This directory contains examples demonstrating how to use the Registry with different key patterns and configurations.
-
-## Examples
-
-### 1. `simple-example.ts` ⭐ **Start Here!**
-**Perfect for beginners!** Demonstrates the simplest possible way to use the Registry:
-- **No RegistryHub required** - just call `createRegistry()`
-- **No scopes needed** - pass empty array `[]` or omit entirely
-- **Basic dependency injection** - register and retrieve services
-- **Service dependencies** - shows how services can depend on each other
-
-Great for simple applications that just need basic dependency injection without complexity.
-
-### 2. `multi-level-keys.ts`
-**Advanced usage with scopes and multi-level keys!** Demonstrates how Registry supports hierarchical key type arrays:
-- **Single level**: `['user']`, `['task']` - SQL vs NoSQL implementations
-- **Two levels**: `['user', 'profile']` - S3 vs Local storage implementations
-- **Three levels**: `['user', 'profile', 'preference']` - Redis implementation
-- **Real scopes**: Production vs development environments
-- **Multiple implementations**: Same interface, different backends
-
-Shows how each key path maps to different implementations via scopes using the real library.
-
-### 3. `registry-hub-types.ts` 🏗️ **Enterprise Architecture**
-**Large-scale application with service organization!** Demonstrates how RegistryHub manages multiple registries for different service types:
-- **Service Categories**: Business logic, data access, infrastructure, communication
-- **Type-based Organization**: Services organized by purpose and responsibility
-- **Cross-Registry Workflows**: Services from different registries working together
-- **Environment Configuration**: Production vs development implementations
-- **Centralized Discovery**: Single hub for all service types
-
-Perfect for enterprise applications that need clean separation of concerns and organized service architecture.
-
-### 4. `registry-statistics-example.ts` 📊 **Usage Analytics**
-**Track and monitor registry usage patterns with scope-aware analytics!** Demonstrates advanced statistics tracking:
-- **Scope-Aware Tracking**: Separate statistics for each kta + scopes combination
-- **Total Call Monitoring**: Track overall `get()` method usage
-- **Detailed Coordinate Records**: Individual tracking for each service/scope pair
-- **Environment Analysis**: Aggregate statistics by environment (prod/dev)
-- **Most/Least Used Services**: Identify usage patterns and bottlenecks
-- **Immutable Statistics**: Safe access to tracking data without affecting internal state
-- **Normalized Scope Handling**: Consistent tracking regardless of scope order
-
-Perfect for monitoring, optimization, understanding service usage patterns, and analyzing environment-specific behavior in production applications.
-
-## Key Concepts Demonstrated
-
-### Simple Usage (simple-example.ts)
-```typescript
-// Import the real registry functionality
-import { createRegistry, createInstance } from '../src/Registry';
-
-// Create a registry - no RegistryHub needed!
-const registry = createRegistry('app');
-
-// Register a service - no scopes needed!
-registry.createInstance(['logger'], [], (coordinate, context) => {
-  const service = new LoggerService();
-  const instance = createInstance(context.registry, coordinate);
-  (instance as any).log = service.log.bind(service);
-  return instance;
-});
-
-// Get the service - no scopes needed!
-const logger = registry.get(['logger']);
-logger.log('Hello from the registry!');
-```
-
-### Multi-Level Key Arrays
-```typescript
-// Different key path levels
-['user']                           // → UserService implementation
-['user', 'profile']                // → UserProfileService implementation
-['user', 'profile', 'preference']  // → UserPreferenceService implementation
-['task']                           // → TaskService implementation
-```
-
-### RegistryHub Usage (registry-hub-types.ts)
-```typescript
-// Import RegistryHub functionality
-import { createRegistryHub } from '../src/RegistryHub';
-import { createRegistry } from '../src/Registry';
-
-// Create a hub to manage multiple registries
-const hub = createRegistryHub();
-
-// Create specialized registries for different service types
-const servicesRegistry = createRegistry('services');      // Business logic
-const dataRegistry = createRegistry('data');              // Data access
-const infraRegistry = createRegistry('infrastructure');   // Infrastructure
-const commRegistry = createRegistry('communication');     // External services
-
-// Register all registries in the hub
-hub.registerRegistry(servicesRegistry);
-hub.registerRegistry(dataRegistry);
-hub.registerRegistry(infraRegistry);
-hub.registerRegistry(commRegistry);
-
-// Register services by type and scope
-servicesRegistry.createInstance(['auth'], ['prod'], (coordinate, context) => {
-  // JWT implementation for production
-});
-
-dataRegistry.createInstance(['user'], ['sql'], (coordinate, context) => {
-  // PostgreSQL implementation
-});
-
-// Retrieve services by type and scope through the hub
-const prodAuth = hub.get('services', ['auth'], { scopes: ['prod'] });
-const sqlUser = hub.get('data', ['user'], { scopes: ['sql'] });
-const cache = hub.get('infrastructure', ['cache'], { scopes: ['dev'] });
-const email = hub.get('communication', ['email'], { scopes: ['prod'] });
-```
-
-### Scope-Based Implementation Selection
-- Multiple implementations per key path
-- Runtime selection via scopes
-- Environment-based switching (prod/dev/test)
-- Feature flags and A/B testing support
-
-### Real-World Use Cases
-- **Database Abstraction**: Different implementations for PostgreSQL, MongoDB, etc.
-- **Environment Selection**: Different implementations for prod/dev
-- **Testing**: Mock implementations with 'test' scope
-- **Microservices**: Each key path represents a different service
-- **Multi-Region**: Different implementations across regions
-
-## Using the Registry
-
-The registry provides a centralized way to manage instances in your application. Here are the main operations you can perform:
-
-### Getting All Coordinates
-
-You can retrieve a list of all coordinates currently registered in the registry:
-
-```typescript
-import { createRegistry } from '@fjell/registry';
-
-const registry = createRegistry('myRegistry');
-
-// Register some instances...
-registry.createInstance(['service'], ['production'], factory1);
-registry.createInstance(['cache', 'redis'], ['development'], factory2);
-
-// Get all coordinates
-const coordinates = registry.getCoordinates();
-console.log(`Found ${coordinates.length} registered coordinates:`);
-coordinates.forEach(coord => {
-  console.log(`- ${coord.toString()}`);
-});
-```
-
-This is useful for debugging, monitoring, or implementing discovery mechanisms in your application.
-
-### Basic Instance Management
-
-## Running Examples
-
-```bash
-# Start with the simple example (recommended)
-npx tsx examples/simple-example.ts
-
-# Run the multi-level keys example
-npx tsx examples/multi-level-keys.ts
-
-# Run the RegistryHub with service types example
-npx tsx examples/registry-hub-types.ts
-
-# Run the coordinate discovery and introspection example
-npx tsx examples/coordinates-example.ts
-
-# Run the RegistryHub cross-registry coordinate discovery example
-npx tsx examples/registry-hub-coordinates-example.ts
-
-# Run the registry statistics tracking example
-npx tsx examples/registry-statistics-example.ts
-
-# Or in Node.js
-node -r esbuild-register examples/simple-example.ts
-node -r esbuild-register examples/multi-level-keys.ts
-node -r esbuild-register examples/registry-hub-types.ts
-node -r esbuild-register examples/coordinates-example.ts
-node -r esbuild-register examples/registry-hub-coordinates-example.ts
-node -r esbuild-register examples/registry-statistics-example.ts
-```
-
-## Integration with Real Fjell Registry
-
-Both examples now use the real library! In actual usage with the built package:
-
-```typescript
-import { createRegistry, createInstance } from '@fjell/registry';
-
-// Simple usage - no RegistryHub, no scopes
-const registry = createRegistry('app');
-
-registry.createInstance(['user'], [], (coordinate, context) => {
-  const service = new UserService();
-  const instance = createInstance(context.registry, coordinate);
-  (instance as any).save = service.save.bind(service);
-  return instance;
-});
-
-const user = registry.get(['user']);
-
-// Advanced usage - with scopes for multiple implementations
-registry.createInstance(['user'], ['sql', 'prod'], (coordinate, context) => {
-  const service = new SqlUserService();
-  const instance = createInstance(context.registry, coordinate);
-  (instance as any).save = service.save.bind(service);
-  return instance;
-});
-
-const prodUser = registry.get(['user'], { scopes: ['prod'] });
-```
-
-## When to Use What
-
-**Use `simple-example.ts` approach when:**
-- You're just getting started
-- You have a simple application
-- You don't need multiple implementations per service
-- You want basic dependency injection
-
-**Use `multi-level-keys.ts` approach when:**
-- You need multiple implementations (prod/dev/test)
-- You have complex service hierarchies
-- You need environment-based switching
-- You're building a large, complex application
-
-**Use `registry-hub-types.ts` approach when:**
-- You're building enterprise-scale applications
-- You need to organize services by type/category
-- You have multiple teams working on different service layers
-- You want clean separation between business logic, data, and infrastructure
-- You need centralized service discovery across service types
-- You're implementing microservices or modular architecture
-
-This approach provides the foundation for the Fjell library's architecture pattern with swappable implementations and enterprise-scale service organization.

package/examples/coordinates-example.ts

@@ -1,253 +0,0 @@
-/**
- * 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);
-}