@fjell/registry 4.4.52 → 4.4.53

package/docs/public/memory.md

@@ -1,430 +0,0 @@
-# Registry Memory Consumption Analysis
-
-> **Generated:** 2025-07-21T04:04:11.643Z
-> **Version:** 4.4.7
-> **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 | 72.50 kB | N/A | 0.000 | 83.01 kB | ✅ PASS |
-| registryHubCreation | Memory overhead of creating a RegistryHub instance | 79.55 kB | N/A | 0.001 | 83.01 kB | ✅ PASS |
-| coordinateCreation | Memory overhead of creating Coordinate instances | 112.55 kB | 1.13 kB | 0.001 | 488.28 kB | ✅ PASS |
-| instanceCreation | Memory overhead of creating Instance objects | 158.22 kB | 1.58 kB | 0.001 | 244.14 kB | ✅ PASS |
-| registryStorage | Memory growth when registering instances in registry | 310.70 kB | 3.11 kB | 0.004 | 390.63 kB | ✅ PASS |
-| multiLevelTree | Memory overhead of multi-level instance tree structures | 215.16 kB | 4.30 kB | 0.005 | 585.94 kB | ✅ PASS |
-| scopedInstances | Memory overhead of instances with multiple scopes | 304.58 kB | 3.05 kB | 0.003 | 610.35 kB | ✅ PASS |
-| registryHubIntegration | Memory overhead of RegistryHub managing multiple registries | 276.75 kB | 2.77 kB | 0.008 | 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 | 3.10 kB ± 4.00 kB | 0.06 ± 0.16 ms | ✅ PASS |
-| 20 | 50 | 2.76 kB ± 2.08 kB | 0.11 ± 0.46 ms | ✅ PASS |
-| 50 | 50 | 2.43 kB ± 2.83 kB | 0.10 ± 0.35 ms | ✅ PASS |
-| 100 | 50 | 2.14 kB ± 1.76 kB | 0.17 ± 0.36 ms | ✅ PASS |
-| 200 | 50 | 2.27 kB ± 2.26 kB | 0.63 ± 1.35 ms | ✅ PASS |
-| 500 | 25 | 2.01 kB ± 1.43 kB | 2.73 ± 3.86 ms | ✅ PASS |
-| 1,000 | 25 | 1.99 kB ± 1.75 kB | 5.18 ± 6.83 ms | ✅ PASS |
-| 2,000 | 25 | 1.86 kB ± 1.59 kB | 4.94 ± 3.50 ms | ✅ PASS |
-| 5,000 | 10 | 1.90 kB ± 1.11 kB | 16.26 ± 4.33 ms | ✅ PASS |
-| 10,000 | 10 | 1.46 kB ± 816 B | 21.16 ± 5.97 ms | ✅ PASS |
-
-### Detailed Statistical Analysis
-
-#### 10 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 3.10 kB
-- Range: 200 B - 28.18 kB
-- Standard Deviation: 4.00 kB
-
-**Creation Time:**
-- Average: 0.06 ms
-- Range: 0.01 - 1.14 ms
-- Standard Deviation: 0.16 ms
-
-#### 20 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.76 kB
-- Range: 200 B - 12.40 kB
-- Standard Deviation: 2.08 kB
-
-**Creation Time:**
-- Average: 0.11 ms
-- Range: 0.02 - 3.28 ms
-- Standard Deviation: 0.46 ms
-
-#### 50 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.43 kB
-- Range: 200 B - 18.86 kB
-- Standard Deviation: 2.83 kB
-
-**Creation Time:**
-- Average: 0.10 ms
-- Range: 0.04 - 2.56 ms
-- Standard Deviation: 0.35 ms
-
-#### 100 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.14 kB
-- Range: 200 B - 10.54 kB
-- Standard Deviation: 1.76 kB
-
-**Creation Time:**
-- Average: 0.17 ms
-- Range: 0.08 - 2.65 ms
-- Standard Deviation: 0.36 ms
-
-#### 200 Instances (50 iterations)
-
-**Memory Per Instance:**
-- Average: 2.27 kB
-- Range: 200 B - 11.64 kB
-- Standard Deviation: 2.26 kB
-
-**Creation Time:**
-- Average: 0.63 ms
-- Range: 0.17 - 7.49 ms
-- Standard Deviation: 1.35 ms
-
-#### 500 Instances (25 iterations)
-
-**Memory Per Instance:**
-- Average: 2.01 kB
-- Range: 200 B - 7.61 kB
-- Standard Deviation: 1.43 kB
-
-**Creation Time:**
-- Average: 2.73 ms
-- Range: 0.43 - 14.56 ms
-- Standard Deviation: 3.86 ms
-
-#### 1,000 Instances (25 iterations)
-
-**Memory Per Instance:**
-- Average: 1.99 kB
-- Range: 200 B - 7.61 kB
-- Standard Deviation: 1.75 kB
-
-**Creation Time:**
-- Average: 5.18 ms
-- Range: 0.81 - 31.10 ms
-- Standard Deviation: 6.83 ms
-
-#### 2,000 Instances (25 iterations)
-
-**Memory Per Instance:**
-- Average: 1.86 kB
-- Range: 607 B - 6.69 kB
-- Standard Deviation: 1.59 kB
-
-**Creation Time:**
-- Average: 4.94 ms
-- Range: 1.82 - 11.65 ms
-- Standard Deviation: 3.50 ms
-
-#### 5,000 Instances (10 iterations)
-
-**Memory Per Instance:**
-- Average: 1.90 kB
-- Range: 1.26 kB - 4.30 kB
-- Standard Deviation: 1.11 kB
-
-**Creation Time:**
-- Average: 16.26 ms
-- Range: 11.01 - 21.74 ms
-- Standard Deviation: 4.33 ms
-
-#### 10,000 Instances (10 iterations)
-
-**Memory Per Instance:**
-- Average: 1.46 kB
-- Range: 200 B - 3.61 kB
-- Standard Deviation: 816 B
-
-**Creation Time:**
-- Average: 21.16 ms
-- Range: 14.28 - 32.53 ms
-- Standard Deviation: 5.97 ms
-
-
-### Memory Efficiency Pattern (Statistical Summary)
-
-The following data shows per-instance memory efficiency with confidence intervals:
-
-```
-Instance Count | Avg Per Instance | StdDev %
-           10 |          3.10 kB | 129.1%
-           20 |          2.76 kB | 75.4%
-           50 |          2.43 kB | 116.5%
-          100 |          2.14 kB | 82.3%
-          200 |          2.27 kB | 99.4%
-          500 |          2.01 kB | 71.3%
-         1000 |          1.99 kB | 88.0%
-         2000 |          1.86 kB | 85.3%
-         5000 |          1.90 kB | 58.6%
-        10000 |          1.46 kB | 54.7%
-```
-
-### 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**: -11.3% (2.14 kB → 1.90 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:** 72.50 kB
-**Memory Per Instance:** N/A
-**Average Time:** 0.000 ms
-
-**Memory Breakdown:**
-- Heap Used: 72.50 kB
-- Heap Total: 0 B
-- External: 40 B
-- RSS: 0 B
-
-**Memory Threshold:** 83.01 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.001 ms
-
-**Memory Breakdown:**
-- Heap Used: 79.55 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 83.01 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.001 ms
-
-**Memory Breakdown:**
-- Heap Used: 112.55 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 488.28 kB
-**Time Threshold:** 0.5 ms
-**Status:** ✅ PASS
-
-### instanceCreation
-
-**Description:** Memory overhead of creating Instance objects
-**Iterations:** 100
-**Total Memory Delta:** 158.22 kB
-**Memory Per Instance:** 1.58 kB
-**Average Time:** 0.001 ms
-
-**Memory Breakdown:**
-- Heap Used: 158.22 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 244.14 kB
-**Time Threshold:** 1 ms
-**Status:** ✅ PASS
-
-### registryStorage
-
-**Description:** Memory growth when registering instances in registry
-**Iterations:** 100
-**Total Memory Delta:** 310.70 kB
-**Memory Per Instance:** 3.11 kB
-**Average Time:** 0.004 ms
-
-**Memory Breakdown:**
-- Heap Used: 310.70 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.16 kB
-**Memory Per Instance:** 4.30 kB
-**Average Time:** 0.005 ms
-
-**Memory Breakdown:**
-- Heap Used: 215.16 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:** 304.58 kB
-**Memory Per Instance:** 3.05 kB
-**Average Time:** 0.003 ms
-
-**Memory Breakdown:**
-- Heap Used: 304.58 kB
-- Heap Total: 0 B
-- External: 0 B
-- RSS: 0 B
-
-**Memory Threshold:** 610.35 kB
-**Time Threshold:** 2 ms
-**Status:** ✅ PASS
-
-### registryHubIntegration
-
-**Description:** Memory overhead of RegistryHub managing multiple registries
-**Iterations:** 20
-**Total Memory Delta:** 276.75 kB
-**Memory Per Instance:** 2.77 kB
-**Average Time:** 0.008 ms
-
-**Memory Breakdown:**
-- Heap Used: 276.75 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**: ≤ 83.01 kB
-- **Registry Hub Creation**: ≤ 83.01 kB
-- **Maximum Registry Overhead**: ≤ 117.19 kB
-
-### Per-Instance Overhead
-- **Instance Creation**: ≤ 2.44 kB per instance
-- **Coordinate Creation**: ≤ 4.88 kB per coordinate
-- **Instance Tree Node**: ≤ 3.91 kB per tree node
-- **Maximum Memory Per Instance**: ≤ 4.88 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**: 12.7% under constraint limit
-- **Per-Instance Efficiency**: 67.6% 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.*

package/docs/public/operations/README.md

@@ -1,121 +0,0 @@
-# API Operations
-
-This section provides comprehensive documentation for all available operations in the Fjell Client API. Each operation supports both Primary Items (PItemApi) and Contained Items (CItemApi) with location-aware variants.
-
-## Quick Reference
-
-### Core CRUD Operations
-- **[`all`](./all.md)** - Retrieve multiple items with query support
-- **[`create`](./create.md)** - Create new items with validation
-- **[`get`](./get.md)** - Retrieve single items by key
-- **[`update`](./update.md)** - Update existing items with partial data
-- **[`remove`](./remove.md)** - Delete items safely
-- **[`one`](./one.md)** - Find single item with query conditions
-
-### Business Logic Operations
-- **[`action`](./action.md)** - Execute business actions on items
-- **[`allAction`](./allAction.md)** - Execute batch actions on collections
-- **[`facet`](./facet.md)** - Retrieve analytics and computed data for items
-- **[`allFacet`](./allFacet.md)** - Retrieve analytics for collections
-
-### Query Operations
-- **[`find`](./find.md)** - Find items using custom finders
-- **[`findOne`](./findOne.md)** - Find single item using custom finders
-
-## Operation Categories
-
-### Primary Item Operations (PItemApi)
-Operations for independent entities that exist at the top level of your API hierarchy:
-
-```typescript
-const userApi = createPItemApi<User, 'user'>('user', ['users'], config);
-
-// Basic CRUD
-const users = await userApi.all({ active: true });
-const user = await userApi.create({ name: 'John', email: 'john@example.com' });
-const foundUser = await userApi.get(userKey);
-const updatedUser = await userApi.update(userKey, { name: 'John Smith' });
-await userApi.remove(userKey);
-
-// Business logic
-await userApi.action(userKey, 'activate', { reason: 'manual' });
-const analytics = await userApi.facet(userKey, 'activity-stats');
-```
-
-### Contained Item Operations (CItemApi)
-Operations for hierarchical entities that require location context:
-
-```typescript
-const taskApi = createCItemApi<Task, 'task', 'user'>('task', ['users', 'tasks'], config);
-
-// Location-aware CRUD
-const userTasks = await taskApi.all({ status: 'pending' }, [userId]);
-const newTask = await taskApi.create({ title: 'Complete project' }, [userId]);
-
-// Location-aware business logic
-await taskApi.allAction('bulk-update', { priority: 'high' }, [userId]);
-const taskMetrics = await taskApi.allFacet('completion-metrics', {}, [userId]);
-```
-
-## Error Handling
-
-All operations include comprehensive error handling with:
-- **Automatic retry logic** for transient failures
-- **Custom error types** for different scenarios
-- **Enhanced error context** for debugging
-- **Configurable retry behavior**
-
-See the [Error Handling Documentation](../error-handling/README.md) for complete details.
-
-## Performance Considerations
-
-### Pagination
-Use `limit` and `offset` in queries for large datasets:
-
-```typescript
-const users = await userApi.all({
-  limit: 50,
-  offset: 100,
-  sort: 'createdAt:desc'
-});
-```
-
-### Batch Operations
-Use `allAction` and `allFacet` for efficient batch processing:
-
-```typescript
-// Efficient batch update
-await userApi.allAction('bulk-update', {
-  lastLoginAt: new Date()
-}, { filter: 'active:true' });
-```
-
-### Caching Strategies
-Implement client-side caching for frequently accessed data:
-
-```typescript
-const cachedUser = await cache.get(userKey) || await userApi.get(userKey);
-```
-
-## Type Safety
-
-All operations are fully typed with TypeScript generics:
-
-```typescript
-interface User extends Item<'user'> {
-  name: string;
-  email: string;
-  active: boolean;
-}
-
-// Type-safe operations
-const userApi = createPItemApi<User, 'user'>('user', ['users'], config);
-const user: User = await userApi.create({ name: 'John', email: 'john@example.com' });
-```
-
-## Next Steps
-
-- Review individual operation documentation for detailed examples
-- Check the [Configuration Guide](../configuration.md) for setup options
-- Explore [Error Handling](../error-handling/README.md) for resilience patterns
-- See [Examples](../../examples-README.md) for complete usage scenarios