@fjell/registry 4.4.11 → 4.4.13

package/docs/memory.md

@@ -1,430 +0,0 @@
-# Registry Memory Consumption Analysis
-
-> **Generated:** 2025-07-21T06:44:48.336Z
-> **Version:** 4.4.10
-> **Node.js:** v22.0.0
-> **Test Environment:** darwin arm64
-
-## Executive Summary
-
-  This document provides a comprehensive analysis of memory efficiency for the Fjell Registry library infrastructure. The tests focus on measuring memory overhead per registry instance to ensure optimal memory scaling and efficiency in production environments.
-
-"Memory efficiency per instance" refers to the average amount of memory used by each registry instance, helping identify how memory usage scales as the number of instances increases.
-
-## Memory Test Results
-
-| Operation | Description | Memory Delta | Per Instance | Avg Time (ms) | Threshold | Status |
-|-----------|-------------|--------------|--------------|---------------|-----------|--------|
-| registryCreation | Memory overhead of creating a Registry instance | 107.76 kB | N/A | 0.002 | 195.31 kB | ✅ PASS |
-| registryHubCreation | Memory overhead of creating a RegistryHub instance | 79.55 kB | N/A | 0.010 | 195.31 kB | ✅ PASS |
-| coordinateCreation | Memory overhead of creating Coordinate instances | 112.55 kB | 1.13 kB | 0.002 | 585.94 kB | ✅ PASS |
-| instanceCreation | Memory overhead of creating Instance objects | 158.21 kB | 1.58 kB | 0.003 | 390.63 kB | ✅ PASS |
-| registryStorage | Memory growth when registering instances in registry | 305.50 kB | 3.06 kB | 0.010 | 390.63 kB | ✅ PASS |
-| multiLevelTree | Memory overhead of multi-level instance tree structures | 215.14 kB | 4.30 kB | 0.072 | 585.94 kB | ✅ PASS |
-| scopedInstances | Memory overhead of instances with multiple scopes | 315.16 kB | 3.15 kB | 0.007 | 976.56 kB | ✅ PASS |
-| registryHubIntegration | Memory overhead of RegistryHub managing multiple registries | 284.06 kB | 2.84 kB | 0.009 | 2.29 MB | ✅ PASS |
-
-## Memory Efficiency Scaling Analysis (Statistical)
-
-### Per-Instance Memory Efficiency Results
-
-| Instance Count | Iterations | Memory Per Instance (Avg ± StdDev) | Time (Avg ± StdDev) | Status |
-|----------------|------------|-------------------------------------|---------------------|--------|
-| 10 | 50 | 2.73 kB ± 2.23 kB | 0.07 ± 0.28 ms | ✅ PASS |
-| 20 | 50 | 2.71 kB ± 2.02 kB | 0.11 ± 0.26 ms | ✅ PASS |
-| 50 | 50 | 2.37 kB ± 1.99 kB | 0.23 ± 0.54 ms | ✅ PASS |
-| 100 | 50 | 2.17 kB ± 1.71 kB | 0.28 ± 0.50 ms | ✅ PASS |
-| 200 | 50 | 2.28 kB ± 2.25 kB | 1.67 ± 4.01 ms | ✅ PASS |
-| 500 | 25 | 2.00 kB ± 1.43 kB | 1.95 ± 3.56 ms | ✅ PASS |
-| 1,000 | 25 | 2.03 kB ± 1.73 kB | 2.81 ± 3.29 ms | ✅ PASS |
-| 2,000 | 25 | 1.86 kB ± 1.39 kB | 9.25 ± 6.91 ms | ✅ PASS |
-| 5,000 | 10 | 1.80 kB ± 1.41 kB | 14.91 ± 14.12 ms | ✅ PASS |
-| 10,000 | 10 | 1.76 kB ± 897 B | 18.79 ± 2.66 ms | ✅ PASS |
-
-### Detailed Statistical Analysis
-
-#### 10 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.73 kB
-- Range: 200 B - 14.25 kB
-- Standard Deviation: 2.23 kB
-
-**Creation Time:**
-- Average: 0.07 ms
-- Range: 0.01 - 2.00 ms
-- Standard Deviation: 0.28 ms
-
-#### 20 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.71 kB
-- Range: 200 B - 11.49 kB
-- Standard Deviation: 2.02 kB
-
-**Creation Time:**
-- Average: 0.11 ms
-- Range: 0.05 - 1.90 ms
-- Standard Deviation: 0.26 ms
-
-#### 50 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.37 kB
-- Range: 200 B - 10.96 kB
-- Standard Deviation: 1.99 kB
-
-**Creation Time:**
-- Average: 0.23 ms
-- Range: 0.05 - 3.83 ms
-- Standard Deviation: 0.54 ms
-
-#### 100 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.17 kB
-- Range: 200 B - 10.54 kB
-- Standard Deviation: 1.71 kB
-
-**Creation Time:**
-- Average: 0.28 ms
-- Range: 0.08 - 2.96 ms
-- Standard Deviation: 0.50 ms
-
-#### 200 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.28 kB
-- Range: 200 B - 11.65 kB
-- Standard Deviation: 2.25 kB
-
-**Creation Time:**
-- Average: 1.67 ms
-- Range: 0.17 - 25.45 ms
-- Standard Deviation: 4.01 ms
-
-#### 500 Instances (25 iterations)
-
-**Memory Per Instance:**
-- Average: 2.00 kB
-- Range: 200 B - 7.61 kB
-- Standard Deviation: 1.43 kB
-
-**Creation Time:**
-- Average: 1.95 ms
-- Range: 0.40 - 15.64 ms
-- Standard Deviation: 3.56 ms
-
-#### 1,000 Instances (25 iterations)
-
-**Memory Per Instance:**
-- Average: 2.03 kB
-- Range: 200 B - 7.61 kB
-- Standard Deviation: 1.73 kB
-
-**Creation Time:**
-- Average: 2.81 ms
-- Range: 0.88 - 15.17 ms
-- Standard Deviation: 3.29 ms
-
-#### 2,000 Instances (25 iterations)
-
-**Memory Per Instance:**
-- Average: 1.86 kB
-- Range: 492 B - 5.84 kB
-- Standard Deviation: 1.39 kB
-
-**Creation Time:**
-- Average: 9.25 ms
-- Range: 1.92 - 36.19 ms
-- Standard Deviation: 6.91 ms
-
-#### 5,000 Instances (10 iterations)
-
-**Memory Per Instance:**
-- Average: 1.80 kB
-- Range: 200 B - 4.66 kB
-- Standard Deviation: 1.41 kB
-
-**Creation Time:**
-- Average: 14.91 ms
-- Range: 4.73 - 55.96 ms
-- Standard Deviation: 14.12 ms
-
-#### 10,000 Instances (10 iterations)
-
-**Memory Per Instance:**
-- Average: 1.76 kB
-- Range: 1.28 kB - 3.61 kB
-- Standard Deviation: 897 B
-
-**Creation Time:**
-- Average: 18.79 ms
-- Range: 14.24 - 23.46 ms
-- Standard Deviation: 2.66 ms
-
-
-### Memory Efficiency Pattern (Statistical Summary)
-
-The following data shows per-instance memory efficiency with confidence intervals:
-
-```
-Instance Count | Avg Per Instance | StdDev %
-           10 |          2.73 kB | 81.7%
-           20 |          2.71 kB | 74.5%
-           50 |          2.37 kB | 83.9%
-          100 |          2.17 kB | 79.0%
-          200 |          2.28 kB | 98.4%
-          500 |          2.00 kB | 71.4%
-         1000 |          2.03 kB | 85.6%
-         2000 |          1.86 kB | 74.9%
-         5000 |          1.80 kB | 78.3%
-        10000 |          1.76 kB | 49.8%
-```
-
-### Statistical Reliability
-
-- **Sample Sizes**: 10: 50 iterations, 20: 50 iterations, 50: 50 iterations, 100: 50 iterations, 200: 50 iterations, 500: 25 iterations, 1000: 25 iterations, 2000: 25 iterations, 5000: 10 iterations, 10000: 10 iterations
-- **Data Quality**: All measurements include statistical analysis with standard deviations
-- **Outlier Detection**: Raw data files available in `./docs/memory-data/` for detailed analysis
-- **Confidence**: Standard deviations indicate measurement reliability and consistency
-
-### Scaling Characteristics (Statistical)
-
-- **Per-Instance Memory Change**: -16.9% (2.17 kB → 1.80 kB)
-- **Memory Efficiency**: Good
-- **Per-Instance Consistency**: Excellent (< 1KB variation)
-- **Statistical Confidence**: High (multiple iterations with standard deviation analysis)
-
-## Detailed Memory Analysis
-
-### registryCreation
-
-**Description:** Memory overhead of creating a Registry instance
-**Iterations:** 100
-**Total Memory Delta:** 107.76 kB
-**Memory Per Instance:** N/A
-**Average Time:** 0.002 ms
-
-**Memory Breakdown:**
-- Heap Used: 107.76 kB
-- Heap Total: 0 B
-- External: 40 B
-- RSS: 0 B
-
-**Memory Threshold:** 195.31 kB
-**Time Threshold:** 1 ms
-**Status:** ✅ PASS
-
-### registryHubCreation
-
-**Description:** Memory overhead of creating a RegistryHub instance
-**Iterations:** 100
-**Total Memory Delta:** 79.55 kB
-**Memory Per Instance:** N/A
-**Average Time:** 0.010 ms
-
-**Memory Breakdown:**
-- Heap Used: 79.55 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 195.31 kB
-**Time Threshold:** 1.5 ms
-**Status:** ✅ PASS
-
-### coordinateCreation
-
-**Description:** Memory overhead of creating Coordinate instances
-**Iterations:** 100
-**Total Memory Delta:** 112.55 kB
-**Memory Per Instance:** 1.13 kB
-**Average Time:** 0.002 ms
-
-**Memory Breakdown:**
-- Heap Used: 112.55 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 585.94 kB
-**Time Threshold:** 0.5 ms
-**Status:** ✅ PASS
-
-### instanceCreation
-
-**Description:** Memory overhead of creating Instance objects
-**Iterations:** 100
-**Total Memory Delta:** 158.21 kB
-**Memory Per Instance:** 1.58 kB
-**Average Time:** 0.003 ms
-
-**Memory Breakdown:**
-- Heap Used: 158.21 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 390.63 kB
-**Time Threshold:** 1 ms
-**Status:** ✅ PASS
-
-### registryStorage
-
-**Description:** Memory growth when registering instances in registry
-**Iterations:** 100
-**Total Memory Delta:** 305.50 kB
-**Memory Per Instance:** 3.06 kB
-**Average Time:** 0.010 ms
-
-**Memory Breakdown:**
-- Heap Used: 305.50 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 390.63 kB
-**Time Threshold:** 1.5 ms
-**Status:** ✅ PASS
-
-### multiLevelTree
-
-**Description:** Memory overhead of multi-level instance tree structures
-**Iterations:** 50
-**Total Memory Delta:** 215.14 kB
-**Memory Per Instance:** 4.30 kB
-**Average Time:** 0.072 ms
-
-**Memory Breakdown:**
-- Heap Used: 215.14 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 585.94 kB
-**Time Threshold:** 2 ms
-**Status:** ✅ PASS
-
-### scopedInstances
-
-**Description:** Memory overhead of instances with multiple scopes
-**Iterations:** 100
-**Total Memory Delta:** 315.16 kB
-**Memory Per Instance:** 3.15 kB
-**Average Time:** 0.007 ms
-
-**Memory Breakdown:**
-- Heap Used: 315.16 kB
-- Heap Total: 256.00 kB
-- External: 0 B
-- RSS: 80.00 kB
-
-**Memory Threshold:** 976.56 kB
-**Time Threshold:** 2 ms
-**Status:** ✅ PASS
-
-### registryHubIntegration
-
-**Description:** Memory overhead of RegistryHub managing multiple registries
-**Iterations:** 20
-**Total Memory Delta:** 284.06 kB
-**Memory Per Instance:** 2.84 kB
-**Average Time:** 0.009 ms
-
-**Memory Breakdown:**
-- Heap Used: 284.06 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 2.29 MB
-**Time Threshold:** 5 ms
-**Status:** ✅ PASS
-
-## Memory Constraints
-
-The following memory constraints are enforced to ensure optimal memory usage:
-
-### Infrastructure Overhead
-- **Registry Creation**: ≤ 195.31 kB
-- **Registry Hub Creation**: ≤ 195.31 kB
-- **Maximum Registry Overhead**: ≤ 117.19 kB
-
-### Per-Instance Overhead
-- **Instance Creation**: ≤ 3.91 kB per instance
-- **Coordinate Creation**: ≤ 5.86 kB per coordinate
-- **Instance Tree Node**: ≤ 3.91 kB per tree node
-- **Maximum Memory Per Instance**: ≤ 7.81 kB
-
-### Memory Efficiency Analysis
-
-The memory efficiency analysis focuses on per-instance memory overhead and how it scales with the number of instances.
-
-- **Registry Overhead Efficiency**: 44.8% under constraint limit
-- **Per-Instance Efficiency**: 79.7% under constraint limit
-
-## Performance Characteristics
-
-### Memory Efficiency Scaling
-- **Per-Instance Consistency**: Memory overhead per instance remains relatively constant as instance count increases
-- **Statistical Validation**: Multiple iterations ensure reliable measurements of per-instance efficiency
-- **Low Variance**: Small standard deviations indicate consistent per-instance memory usage
-- **Predictable Efficiency**: Memory efficiency per instance is predictable and optimized
-
-### Optimization Features
-- **Efficient Data Structures**: Uses optimized tree structures for instance storage
-- **Minimal Overhead**: Core registry infrastructure has very low memory footprint
-- **Consistent Performance**: Statistical analysis shows reliable memory patterns
-
-## Data Files
-
-Raw measurement data is available in the following files:
-- `./docs/memory-data/scaling-10-instances.json`
-- `./docs/memory-data/scaling-20-instances.json`
-- `./docs/memory-data/scaling-50-instances.json`
-- `./docs/memory-data/scaling-100-instances.json`
-- `./docs/memory-data/scaling-200-instances.json`
-- `./docs/memory-data/scaling-500-instances.json`
-- `./docs/memory-data/scaling-1000-instances.json`
-- `./docs/memory-data/scaling-2000-instances.json`
-- `./docs/memory-data/scaling-5000-instances.json`
-- `./docs/memory-data/scaling-10000-instances.json`
-
-These files contain all individual measurements, allowing for detailed statistical analysis and trend identification.
-
-## Recommendations
-
-### Memory Management
-1. **Monitor Instance Count**: Keep track of total instances across all registries
-2. **Statistical Analysis**: Use the statistical data to understand memory variance
-3. **Trend Analysis**: Review raw data files to identify memory usage patterns
-4. **Cleanup**: Ensure proper cleanup of unused instances and registries
-
-### Performance Optimization
-1. **Batch Operations**: Create instances in batches when possible
-2. **Registry Reuse**: Reuse registries instead of creating new ones frequently
-3. **Statistical Monitoring**: Use the statistical baselines to detect anomalies
-4. **Constraint Monitoring**: Regularly run memory tests to ensure constraints are met
-
-## Troubleshooting
-
-### Memory Issues
-If memory tests fail, consider:
-
-1. **Statistical Significance**: Check if failures are consistent across multiple iterations
-2. **Variance Analysis**: High standard deviations may indicate unstable conditions
-3. **Raw Data Review**: Examine individual measurements in data files for patterns
-4. **System Resources**: Ensure adequate system memory is available during testing
-
-### Constraint Violations
-If memory constraints are exceeded:
-
-1. **Statistical Confidence**: Verify violations are consistent across iterations
-2. **Trend Analysis**: Use historical data to identify if this is a regression
-3. **Outlier Investigation**: Check raw measurements for outliers affecting averages
-4. **Update Thresholds**: Consider updating constraints based on statistical analysis
-
----
-
-*This document is automatically generated during memory testing and includes statistical analysis of multiple iterations. Raw data files are saved for detailed analysis.*