@fjell/registry 4.4.52 → 4.4.53

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/registry",
   "description": "Dependency injection and service location system for the Fjell ecosystem",
-  "version": "4.4.52",
+  "version": "4.4.53",
   "keywords": [
     "registry",
     "dependency-injection",
@@ -39,13 +39,13 @@
     "docs:test": "cd docs && npm run test"
   },
   "dependencies": {
-    "@fjell/core": "^4.4.50",
-    "@fjell/logging": "^4.4.49"
+    "@fjell/core": "^4.4.51",
+    "@fjell/logging": "^4.4.50"
   },
   "devDependencies": {
     "@eslint/eslintrc": "^3.3.1",
     "@eslint/js": "^9.32.0",
-    "@fjell/eslint-config": "^1.1.25",
+    "@fjell/eslint-config": "^1.1.28",
     "@swc/core": "^1.13.2",
     "@tsconfig/recommended": "^1.0.10",
     "@types/node": "^22.10.0",

package/API.md

@@ -1,62 +0,0 @@
-# API Reference
-
-Complete Registry API documentation and method reference.
-
-## Core Registry Interface
-
-```typescript
-interface Registry {
-  readonly type: string; // Mandatory type identifier
-  createInstance: <...>(...) => Instance<...>;
-  get: (...) => Instance | null;
-  getCoordinates: () => Coordinate[]; // Discover all registered coordinates
-  instanceTree: InstanceTree;
-}
-```
-
-## Primary Methods
-
-### `createRegistry(type: string): Registry`
-Creates a new registry with the specified type identifier.
-
-### `registry.createInstance(kta, scopes, factory)`
-Registers a new service instance with the given key type array and scopes.
-
-### `registry.get(kta, options)`
-Retrieves a service instance by key type array and scope options.
-
-### `registry.getCoordinates(): Coordinate[]`
-Returns all registered coordinates for service discovery and introspection.
-
-## RegistryHub Interface
-
-```typescript
-interface RegistryHub {
-  registerRegistry: (registry: Registry) => void;
-  get: (registryType: string, kta: string[], options?: GetOptions) => Instance | null;
-  getRegistries: () => Registry[];
-  getAllCoordinates: () => Array<{coordinate: Coordinate, registryType: string}>;
-}
-```
-
-## Coordinate System
-
-```typescript
-interface Coordinate {
-  kta: string[]; // Key Type Array - hierarchical identifiers
-  scopes: string[]; // Context qualifiers
-}
-```
-
-## Complete Documentation
-
-For comprehensive API documentation with detailed examples, implementation patterns, and advanced usage scenarios, see the **Foundation** section which contains the complete Registry documentation including:
-
-- Interface definitions and type signatures
-- Detailed method documentation with examples
-- Registry and RegistryHub patterns
-- Coordinate system explanation
-- Service discovery and introspection
-- Error handling and best practices
-
-The Foundation section serves as the authoritative API reference with full context and examples.

package/GETTING_STARTED.md

@@ -1,69 +0,0 @@
-# Getting Started
-
-Quick start guide to using Fjell Registry in your applications.
-
-## Installation
-
-```bash
-npm install @fjell/registry
-```
-
-## Basic Usage
-
-The simplest way to get started with Registry:
-
-```typescript
-import { createRegistry, createInstance } from '@fjell/registry'
-
-// Create a registry with a type identifier
-const registry = createRegistry('services')
-
-// Register a simple service
-registry.createInstance(['logger'], [], (coordinate, context) => {
-  const service = new LoggerService()
-  const instance = createInstance(context.registry, coordinate)
-
-  // Attach service methods to the instance
-  (instance as any).log = service.log.bind(service)
-  return instance
-})
-
-// Retrieve and use the service
-const logger = registry.get(['logger'], [])
-logger?.log('Hello from Registry!')
-```
-
-## Core Concepts Quick Reference
-
-- **Registry**: Central service container with a mandatory type identifier
-- **Coordinate**: Unique identifier using key types + scopes
-- **Instance**: Registered service with coordinate and registry reference
-- **Scopes**: Context qualifiers like environment or implementation type
-
-## Next Steps
-
-- Check out the **Examples** section for complete working examples
-- Read the **Foundation** section for deep understanding of concepts
-- Explore the **API Reference** for complete method documentation
-
-## Common Patterns
-
-### Single Registry (Simple Apps)
-```typescript
-const registry = createRegistry('app')
-// Register all your services here
-```
-
-### Multiple Registries (Enterprise)
-```typescript
-const servicesRegistry = createRegistry('services')
-const dataRegistry = createRegistry('data')
-const cacheRegistry = createRegistry('cache')
-```
-
-### Scoped Services
-```typescript
-// Different implementations for different environments
-registry.createInstance(['database'], ['postgresql'], ...)
-registry.createInstance(['database'], ['firestore'], ...)
-```

package/build.js

@@ -1,38 +0,0 @@
-import { build } from 'esbuild';
-import { execSync } from 'child_process';
-
-// Generate TypeScript declarations first
-console.log('Generating TypeScript declarations...');
-try {
-  execSync('npx tsc --emitDeclarationOnly', { stdio: 'inherit' });
-  console.log('TypeScript declarations generated successfully!');
-} catch (error) {
-  console.error('Failed to generate TypeScript declarations:', error.message);
-  process.exit(1);
-}
-
-// Build cross-platform version that works in both Node.js and browser
-console.log('Building cross-platform version...');
-await build({
-  entryPoints: ['src/index.ts'],
-  bundle: true,
-  platform: 'neutral', // Neutral platform for cross-platform compatibility
-  target: 'es2022',
-  format: 'esm',
-  outfile: 'dist/index.js',
-  external: [
-    'console',
-    '@fjell/core',
-    '@fjell/logging'
-  ], // Keep external dependencies as they should be installed separately
-  define: {
-    'process.env.NODE_ENV': '"production"'
-  },
-  metafile: true,
-  minify: false, // Keep readable for debugging
-});
-
-console.log('Build completed successfully!');
-console.log(`- Cross-platform build: dist/index.js`);
-console.log(`- TypeScript declarations: dist/index.d.ts`);
-console.log('This build works in both Node.js and browser environments');

package/docs/README.md

@@ -1,74 +0,0 @@
-# Fjell Registry Documentation Site
-
-This is a React-based documentation site for the Fjell Registry package. It provides an interactive and modern way to view the project documentation with syntax highlighting and responsive design.
-
-## Features
-
-- **Responsive Design** - Works on desktop, tablet, and mobile
-- **Modern UI** - Clean, modern interface with Fjell branding
-- **Syntax Highlighting** - Code blocks with proper syntax highlighting
-- **Markdown Support** - Full GitHub Flavored Markdown support
-- **Fast Loading** - Built with Vite for optimal performance
-
-## Development
-
-### Prerequisites
-
-- Node.js 22+
-- npm
-
-### Local Development
-
-```bash
-# Install dependencies
-npm install
-
-# Start development server
-npm run dev
-
-# Build for production
-npm run build
-
-# Preview production build
-npm run preview
-```
-
-### Testing
-
-```bash
-# Run tests
-npm run test
-
-# Run tests in watch mode
-npm run test:watch
-```
-
-## Deployment
-
-The site is automatically deployed to GitHub Pages when changes are pushed to the main branch or any release branch. The deployment is handled by the `.github/workflows/deploy-docs.yml` workflow.
-
-## Architecture
-
-- **React 19** - Modern React with hooks
-- **TypeScript** - Full type safety
-- **Vite** - Fast build tool and dev server
-- **React Markdown** - Renders README.md dynamically
-- **React Syntax Highlighter** - Beautiful code syntax highlighting
-- **Vitest** - Fast unit testing framework
-
-## Configuration
-
-The site is configured to:
-- Fetch the main README.md from the project root
-- Use the `/fjell-registry/` base path for GitHub Pages
-- Support dark theme code highlighting
-- Include responsive breakpoints for mobile devices
-
-## Contributing
-
-The documentation site automatically reflects changes to the main README.md file. To update the site itself:
-
-1. Make changes to the React components in `src/`
-2. Test locally with `npm run dev`
-3. Commit your changes
-4. The site will automatically deploy via GitHub Actions

package/docs/TIMING_NODE_OPTIMIZATION.md

@@ -1,207 +0,0 @@
-# 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
-npm 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
-npm run test:timing
-
-# Run optimized timing tests
-npm 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

@@ -1,170 +0,0 @@
-# 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
-npm run test:timing
-
-# Run all tests (including timing tests)
-npm 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.