@fjell/registry 4.4.5 → 4.4.6

package/dist/types.d.ts

@@ -0,0 +1,90 @@
+import { Instance } from './Instance';
+import { Coordinate } from './Coordinate';
+/**
+ * The RegistryHub interface provides a higher-level registry that manages multiple Registry instances.
+ */
+export interface RegistryHub {
+    /**
+     * Creates a new registry instance using a RegistryFactory and automatically registers it.
+     */
+    readonly createRegistry: (type: string, factory: RegistryFactory) => Registry;
+    /**
+     * Registers a registry instance, using the registry's type property as the key.
+     */
+    readonly registerRegistry: (registry: Registry) => void;
+    /**
+     * Retrieves an instance by delegating to the appropriate registry.
+     */
+    readonly get: (type: string, kta: string[], options?: {
+        scopes?: string[];
+    }) => Instance<any, any | never, any | never, any | never, any | never, any | never> | null;
+    /**
+     * Retrieves a registry instance by its type key.
+     */
+    readonly getRegistry: (type: string) => Registry | null;
+    /**
+     * Lists all registered type keys.
+     */
+    readonly getRegisteredTypes: () => string[];
+    /**
+     * Removes a registry from the hub.
+     */
+    readonly unregisterRegistry: (type: string) => boolean;
+}
+/**
+ * Factory function for creating instances. This function receives a coordinate and context
+ * and returns a fully initialized instance.
+ */
+export type InstanceFactory<S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never> = (coordinate: Coordinate<S, L1, L2, L3, L4, L5>, context: {
+    registry: Registry;
+    registryHub?: RegistryHub;
+}) => Instance<S, L1, L2, L3, L4, L5>;
+/**
+ * Factory function for creating a Registry instance. This function receives the type and hub
+ * and returns a fully initialized registry.
+ */
+export type RegistryFactory = (type: string, registryHub?: RegistryHub) => Registry;
+/**
+ * Tree structure representing the hierarchy of instances
+ */
+export interface InstanceTree {
+    [keyType: string]: InstanceTreeNode;
+}
+export interface InstanceTreeNode {
+    instances: ScopedInstance[];
+    children: InstanceTree | null;
+}
+export interface ScopedInstance {
+    scopes?: string[];
+    instance: Instance<any, any | never, any | never, any | never, any | never, any | never>;
+}
+/**
+ * The Registry interface provides a central registry for managing and accessing instances of services.
+ * It serves as a dependency injection container that allows libraries to reference and access
+ * other library instances they depend on.
+ */
+export interface Registry {
+    /** The type identifier for this registry (e.g., 'services', 'data', 'cache') */
+    readonly type: string;
+    /** Optional reference to the RegistryHub that created this registry */
+    readonly registryHub?: RegistryHub;
+    /**
+     * Creates and registers a new instance in the registry in one atomic operation.
+     */
+    createInstance: <S extends string, L1 extends string = never, L2 extends string = never, L3 extends string = never, L4 extends string = never, L5 extends string = never>(kta: S[], scopes: string[], factory: InstanceFactory<S, L1, L2, L3, L4, L5>) => Instance<S, L1, L2, L3, L4, L5>;
+    /**
+     * Registers an existing instance in the registry (for migration/advanced use cases).
+     * @deprecated Use createInstance instead for new code
+     */
+    register: (kta: string[], instance: Instance<any, any | never, any | never, any | never, any | never, any | never>, options?: {
+        scopes?: string[];
+    }) => void;
+    /**
+     * Retrieves an instance from the registry.
+     */
+    get: (kta: string[], options?: {
+        scopes?: string[];
+    }) => Instance<any, any | never, any | never, any | never, any | never, any | never> | null;
+    /** The tree structure representing the hierarchy of instances */
+    instanceTree: InstanceTree;
+}

package/docs/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/TIMING_README.md

@@ -0,0 +1,170 @@
+# Timing Test System
+
+This document explains the timing test system implemented for the @fjell/registry project.
+
+## Overview
+
+The timing test system measures the performance of key operations in the fjell-registry library using robust multi-round testing and generates comprehensive documentation including heatmap visualizations. It runs hundreds of test rounds to smooth out system load variations and provides reliable performance metrics. The system ensures that performance remains within acceptable bounds and helps detect performance regressions.
+
+## Running Timing Tests
+
+```bash
+# Run timing tests specifically
+pnpm run test:timing
+
+# Run all tests (including timing tests)
+pnpm test
+```
+
+## Measured Operations
+
+The timing system measures the following operations:
+
+- **createRegistry**: Time to create a new registry
+- **createRegistryHub**: Time to create a new registry hub
+- **createInstance**: Time to create a new instance
+- **registerInstance**: Time to register an instance in registry
+- **lookupInstance**: Time to lookup an existing instance from registry
+- **completeWorkflow**: Time for complete workflow including all operations
+
+### Scaling Tests
+
+Additionally, the system includes comprehensive scaling tests that measure performance across a wide range of tree sizes:
+
+- **Tree sizes tested**: 10, 20, 50, 100, 200, 500, 1000, 2000, 5000, 10000, 20000, 50000, 100000
+- **registerInstance_[size]**: Registration performance with varying numbers of existing items
+- **lookupInstance_[size]**: Lookup performance with different tree sizes
+
+These extensive tests help identify potential O(n) performance issues and ensure the registry scales well from small applications to enterprise-scale deployments.
+
+## Timing Constraints
+
+The following timing constraints are enforced (all values in microseconds):
+
+### Basic Operations
+- **createRegistry**: ≤ 5000µs (5ms)
+- **createRegistryHub**: ≤ 5000µs (5ms)
+- **createInstance**: ≤ 10000µs (10ms)
+- **lookupInstance**: ≤ 2000µs (2ms)
+- **registerInstance**: ≤ 5000µs (5ms)
+- **completeWorkflow**: ≤ 25000µs (25ms)
+
+### Scaling Operations
+- **registerInstance** (≤100 items): ≤ 5000µs (5ms)
+- **registerInstance** (100-1000 items): ≤ 10000µs (10ms)
+- **registerInstance** (1000-10000 items): ≤ 20000µs (20ms)
+- **registerInstance** (>10000 items): ≤ 50000µs (50ms)
+- **lookupInstance** (≤100 items): ≤ 2000µs (2ms)
+- **lookupInstance** (100-1000 items): ≤ 5000µs (5ms)
+- **lookupInstance** (1000-10000 items): ≤ 10000µs (10ms)
+- **lookupInstance** (>10000 items): ≤ 25000µs (25ms)
+
+## Configuration
+
+### Adjusting Timing Constraints
+
+Edit the `TIMING_CONSTRAINTS` object in `tests/timing.test.ts`:
+
+```typescript
+const TIMING_CONSTRAINTS: TimingConstraints = {
+  createRegistry: 5000,      // 5000µs (5ms) max
+  createRegistryHub: 5000,   // 5000µs (5ms) max
+  createInstance: 10000,     // 10000µs (10ms) max
+  lookupInstance: 2000,      // 2000µs (2ms) max
+  registerInstance: 5000,    // 5000µs (5ms) max
+};
+```
+
+### Adjusting Test Iterations
+
+Change the `ITERATIONS` constant to adjust the number of test iterations:
+
+```typescript
+const ITERATIONS = 1000; // Number of iterations for timing tests
+```
+
+## Generated Documentation
+
+When timing tests run, they automatically generate documentation at `./docs/timing.md`. This file includes:
+
+- Performance summary table for basic operations
+- Scaling performance table showing results for different tree sizes
+- **SVG performance graph** visualizing scaling trends (`./docs/scaling-performance.svg`)
+- **SVG performance range chart** showing performance consistency with ±1σ bands (`./docs/timing-range.svg`)
+- Detailed timing results for each operation (in microseconds)
+- Performance analysis and scaling recommendations
+- System information (Node.js version, platform, etc.)
+
+### Multi-Round Testing
+
+The system runs 100 test rounds (configurable) for smaller tree sizes and reduces rounds for larger sizes to balance thoroughness with test duration:
+
+- **≤1000 items**: 100 rounds × 200 iterations = ~20,000 measurements per operation
+- **1000-10000 items**: 50 rounds × 100 iterations = ~5,000 measurements per operation
+- **>10000 items**: 25 rounds × 50 iterations = ~1,250 measurements per operation
+
+For performance range visualization, the system calculates mean and standard deviation for each tree size, displaying ±1σ confidence bands that show performance consistency.
+
+**Randomized Batching**: Instead of running all iterations sequentially, the system uses randomized batch sizes (10-50 iterations) with brief pauses between batches. This approach simulates real-world usage patterns and prevents artificial performance artifacts from caching, JIT optimization, and memory allocation patterns.
+
+This comprehensive approach provides robust results that smooth out system load variations and clearly show performance characteristics and variability.
+
+## Best Practices
+
+### When to Update Constraints
+
+- **After optimization**: If you've improved performance, consider tightening constraints
+- **Hardware changes**: Adjust constraints when changing build/test infrastructure
+- **Performance regressions**: Investigate and fix before loosening constraints
+
+### Interpreting Results
+
+- **Average Time**: Most important metric for consistent performance
+- **Max Time**: Helps identify performance spikes
+- **Min Time**: Usually very low due to CPU caching effects
+
+### Troubleshooting Failed Tests
+
+If timing tests fail:
+
+1. **Check recent changes**: Review code changes that might affect performance
+2. **System load**: Ensure the system isn't under heavy load during testing
+3. **Multiple runs**: Run tests multiple times to account for system variance
+4. **Profile code**: Use Node.js profiling tools to identify bottlenecks
+
+## Integration with CI/CD
+
+The timing tests are designed to be run in CI/CD pipelines:
+
+- Tests fail if performance thresholds are exceeded
+- Documentation is automatically updated on each run
+- Results can be tracked over time to monitor performance trends
+
+## File Structure
+
+```
+docs/
+├── timing.md           # Generated timing report (auto-updated)
+└── TIMING_README.md    # This documentation file
+
+tests/
+└── timing.test.ts      # Timing test implementation
+```
+
+## Maintenance
+
+### Regular Tasks
+
+1. **Review thresholds** quarterly to ensure they remain appropriate
+2. **Update documentation** after significant performance improvements
+3. **Monitor trends** in the generated timing reports over releases
+
+### Release Process
+
+The timing documentation (`docs/timing.md`) should be:
+
+1. Generated before each release
+2. Committed to the repository
+3. Published with the package
+
+This ensures users can see performance characteristics of each version.