@fjell/registry 4.4.7 → 4.4.9

package/docs/public/examples-README.md

@@ -0,0 +1,222 @@
+# 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.
+
+## 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
+
+# Or in Node.js
+node -r esbuild-register examples/simple-example.ts
+node -r esbuild-register examples/registry-hub-types.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

@@ -0,0 +1 @@
+ 

package/docs/public/memory-overhead.svg

@@ -0,0 +1,120 @@
+<?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>