@fjell/registry 4.4.51 → 4.4.53

package/docs/public/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/docs/public/fjell-icon.svg

@@ -1 +0,0 @@
- 

package/docs/public/memory-overhead.svg

@@ -1,120 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<svg width="1200" height="800" xmlns="http://www.w3.org/2000/svg">
-  <style>
-    .axis { stroke: #333; stroke-width: 1; }
-    .grid { stroke: #ddd; stroke-width: 0.5; }
-    .label { font-family: Arial, sans-serif; font-size: 14px; fill: #333; }
-    .title { font-family: Arial, sans-serif; font-size: 16px; font-weight: bold; fill: #333; }
-    .subtitle { font-family: Arial, sans-serif; font-size: 12px; fill: #666; }
-    .per-instance { stroke: #3498db; stroke-width: 3; fill: none; }
-    .per-instance-dot { fill: #3498db; }
-    .legend { font-family: Arial, sans-serif; font-size: 12px; fill: #333; }
-    .axis-title { font-family: Arial, sans-serif; font-size: 16px; font-weight: bold; fill: #333; }
-    .metadata-section { font-family: Arial, sans-serif; font-size: 14px; font-weight: bold; fill: #444; }
-    .metadata-label { font-family: Arial, sans-serif; font-size: 10px; fill: #666; }
-    .metadata-value { font-family: Arial, sans-serif; font-size: 10px; fill: #333; }
-  </style>
-
-  <!-- Background -->
-  <rect width="1200" height="800" fill="white"/>
-
-  <!-- Title -->
-  <text x="600" y="25" text-anchor="middle" class="title">Memory Efficiency Per Instance</text>
-  <text x="600" y="45" text-anchor="middle" class="subtitle">Average memory overhead per registry instance across different scale sizes</text>
-
-  <!-- Plot area -->
-  <g transform="translate(110,60)">
-
-    <!-- Grid lines (Y-axis - memory in KB) -->
-    <line x1="0" y1="355.57592837740003" x2="990" y2="355.57592837740003" class="grid"/>
-    <text x="-10" y="359.57592837740003" text-anchor="end" class="label">2KB</text>
-    <line x1="0" y1="153.13821696732998" x2="990" y2="153.13821696732998" class="grid"/>
-    <text x="-10" y="157.13821696732998" text-anchor="end" class="label">5KB</text>
-    <line x1="0" y1="0" x2="990" y2="0" class="grid"/>
-    <text x="-10" y="4" text-anchor="end" class="label">10KB</text>
-    <line x1="0" y1="0" x2="0" y2="460" class="grid"/>
-    <text x="0" y="480" text-anchor="middle" class="label">10</text>
-    <line x1="99.33989856911381" y1="0" x2="99.33989856911381" y2="460" class="grid"/>
-    <text x="99.33989856911381" y="480" text-anchor="middle" class="label">20</text>
-    <line x1="230.6601014308862" y1="0" x2="230.6601014308862" y2="460" class="grid"/>
-    <text x="230.6601014308862" y="480" text-anchor="middle" class="label">50</text>
-    <line x1="330" y1="0" x2="330" y2="460" class="grid"/>
-    <text x="330" y="480" text-anchor="middle" class="label">100</text>
-    <line x1="429.3398985691138" y1="0" x2="429.3398985691138" y2="460" class="grid"/>
-    <text x="429.3398985691138" y="480" text-anchor="middle" class="label">200</text>
-    <line x1="560.6601014308862" y1="0" x2="560.6601014308862" y2="460" class="grid"/>
-    <text x="560.6601014308862" y="480" text-anchor="middle" class="label">500</text>
-    <line x1="660" y1="0" x2="660" y2="460" class="grid"/>
-    <text x="660" y="480" text-anchor="middle" class="label">1k</text>
-    <line x1="759.3398985691139" y1="0" x2="759.3398985691139" y2="460" class="grid"/>
-    <text x="759.3398985691139" y="480" text-anchor="middle" class="label">2k</text>
-    <line x1="890.6601014308862" y1="0" x2="890.6601014308862" y2="460" class="grid"/>
-    <text x="890.6601014308862" y="480" text-anchor="middle" class="label">5k</text>
-    <line x1="990" y1="0" x2="990" y2="460" class="grid"/>
-    <text x="990" y="480" text-anchor="middle" class="label">10k</text>
-    <!-- Y-axis -->
-    <line x1="0" y1="0" x2="0" y2="460" class="axis"/>
-
-    <!-- X-axis -->
-    <line x1="0" y1="460" x2="990" y2="460" class="axis"/>
-
-    <!-- Axis labels -->
-    <text x="495" y="510" text-anchor="middle" class="axis-title">Instance Count - Log Scale</text>
-    <text transform="rotate(-90,-70,230)" x="-70" y="230" text-anchor="middle" class="axis-title">Memory Usage (KB)</text>
-    <path d="M 0 240.70120928043835 L 99.33989856911381 282.22270579627764 L 230.6601014308862 327.2110056876071 L 330 354.03530806378257 L 429.3398985691138 346.21437843228813 L 560.6601014308862 360.1862852477646 L 660 352.43697251573866 L 759.3398985691139 365.33853358657484 L 890.6601014308862 349.28769665195966 L 990 410.70050555725993" class="per-instance"/>
-    <circle cx="0" cy="240.70120928043835" r="4" class="per-instance-dot"/>
-    <circle cx="99.33989856911381" cy="282.22270579627764" r="4" class="per-instance-dot"/>
-    <circle cx="230.6601014308862" cy="327.2110056876071" r="4" class="per-instance-dot"/>
-    <circle cx="330" cy="354.03530806378257" r="4" class="per-instance-dot"/>
-    <circle cx="429.3398985691138" cy="346.21437843228813" r="4" class="per-instance-dot"/>
-    <circle cx="560.6601014308862" cy="360.1862852477646" r="4" class="per-instance-dot"/>
-    <circle cx="660" cy="352.43697251573866" r="4" class="per-instance-dot"/>
-    <circle cx="759.3398985691139" cy="365.33853358657484" r="4" class="per-instance-dot"/>
-    <circle cx="890.6601014308862" cy="349.28769665195966" r="4" class="per-instance-dot"/>
-    <circle cx="990" cy="410.70050555725993" r="4" class="per-instance-dot"/>
-    <!-- Legend -->
-    <g transform="translate(20, 20)">
-      <rect x="0" y="0" width="190" height="60" fill="white" stroke="#ccc" stroke-width="1"/>
-
-      <!-- Memory Per Instance Legend -->
-      <text x="10" y="20" class="legend" font-weight="bold">Memory Per Instance</text>
-      <line x1="10" y1="30" x2="40" y2="30" class="per-instance"/>
-      <circle cx="25" cy="30" r="3" class="per-instance-dot"/>
-      <text x="45" y="34" class="legend">Average Performance</text>
-    </g>
-
-  </g>
-
-  <!-- Test Metadata Section - match timing chart layout exactly -->
-  <g transform="translate(50, 620)">
-    <!-- Left Column: System Information -->
-    <g transform="translate(20, 20)">
-      <text x="0" y="0" class="metadata-section">System Information</text>
-
-      <text x="0" y="25" class="metadata-label">Test Date:</text>
-      <text x="150" y="25" class="metadata-value">2025-07-21</text>
-
-      <text x="0" y="45" class="metadata-label">Package Version:</text>
-      <text x="150" y="45" class="metadata-value">@fjell/registry v4.4.7</text>
-
-      <text x="0" y="65" class="metadata-label">Node.js Version:</text>
-      <text x="150" y="65" class="metadata-value">v22.0.0 (darwin arm64)</text>
-
-      <text x="0" y="85" class="metadata-label">Platform:</text>
-      <text x="150" y="85" class="metadata-value">darwin arm64</text>
-
-      <text x="0" y="105" class="metadata-label">Compiler:</text>
-      <text x="150" y="105" class="metadata-value">TypeScript + Vite</text>
-    </g>
-
-    <!-- Right Column: Test Notes -->
-    <g transform="translate(400, 20)">
-      <text x="0" y="0" class="metadata-section">Test Notes</text>
-      <text x="0" y="25" class="metadata-label">• Memory measurements use Node.js process.memoryUsage() with heap precision</text>
-      <text x="0" y="42" class="metadata-label">• Each test includes garbage collection to minimize measurement variance</text>
-      <text x="0" y="59" class="metadata-label">• Logging is mocked during memory tests to eliminate overhead</text>
-      <text x="0" y="76" class="metadata-label">• Tests verify memory efficiency and consistency across instance counts</text>
-      <text x="0" y="93" class="metadata-label">• Statistical analysis ensures reliable performance measurements</text>
-    </g>
-  </g>
-</svg>