@fjell/registry 4.4.13 → 4.4.16

package/API.md

@@ -0,0 +1,62 @@
+# 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

@@ -0,0 +1,69 @@
+# 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/docs/docs.config.ts

@@ -4,7 +4,13 @@ interface DocsConfig {
   port: number;
   branding: {
     theme: string;
+    tagline: string;
+    logo?: string;
     backgroundImage?: string;
+    primaryColor?: string;
+    accentColor?: string;
+    github?: string;
+    npm?: string;
   };
   sections: Array<{
     id: string;
@@ -12,6 +18,10 @@ interface DocsConfig {
     subtitle: string;
     file: string;
   }>;
+  filesToCopy: Array<{
+    source: string;
+    destination: string;
+  }>;
   plugins?: any[];
   version: {
     source: string;
@@ -22,88 +32,63 @@ interface DocsConfig {
 }
 
 const config: DocsConfig = {
-  projectName: 'fjell-http-api',
-  basePath: '/http-api/',
-  port: 3002,
+  projectName: 'Fjell Registry',
+  basePath: '/registry/',
+  port: 3001,
   branding: {
-    theme: 'http-api',
-    backgroundImage: '/pano.png'
+    theme: 'registry',
+    tagline: 'Common Registry for Fjell',
+    backgroundImage: '/pano.png',
+    github: 'https://github.com/getfjell/registry',
+    npm: 'https://www.npmjs.com/package/@fjell/registry'
   },
   sections: [
     {
       id: 'overview',
       title: 'Foundation',
       subtitle: 'Core concepts & philosophy',
-      file: ''
+      file: '/registry/README.md'
     },
     {
       id: 'getting-started',
       title: 'Getting Started',
-      subtitle: 'Your first HTTP API calls',
-      file: ''
+      subtitle: 'Your first registry operations',
+      file: '/registry/GETTING_STARTED.md'
     },
     {
       id: 'api-reference',
       title: 'API Reference',
       subtitle: 'Complete method documentation',
-      file: ''
+      file: '/registry/API.md'
     },
     {
       id: 'examples',
       title: 'Examples',
       subtitle: 'Code examples & usage patterns',
-      file: '/http-api/examples/README.md'
+      file: '/registry/examples-README.md'
     }
   ],
-  plugins: [],
-  version: {
-    source: 'package.json'
-  },
-  customContent: {
-    'overview': () => {
-      return `# Foundation
-
-Core concepts and philosophy behind Fjell HTTP API.
-
-This library provides a simple and powerful HTTP client for making API requests with comprehensive error handling and response parsing.`;
+  filesToCopy: [
+    {
+      source: '../README.md',
+      destination: 'public/README.md'
     },
-    'getting-started': () => {
-      return `# Getting Started
-
-Your first HTTP API calls with Fjell.
-
-## Installation
-
-\`\`\`bash
-npm install @fjell/http-api
-\`\`\`
-
-## Basic Usage
-
-\`\`\`typescript
-import { HttpClient } from '@fjell/http-api'
-
-const client = new HttpClient({
-  baseURL: 'https://api.example.com'
-})
-
-const response = await client.get('/users')
-\`\`\``;
+    {
+      source: '../examples/README.md',
+      destination: 'public/examples-README.md'
     },
-    'api-reference': () => {
-      return `# API Reference
-
-Complete method documentation for Fjell HTTP API.
-
-## Methods
-
-### GET Requests
-### POST Requests
-### PUT Requests
-### DELETE Requests
-
-Complete documentation coming soon...`;
+    {
+      source: '../GETTING_STARTED.md',
+      destination: 'public/GETTING_STARTED.md'
+    },
+    {
+      source: '../API.md',
+      destination: 'public/API.md'
     }
+  ],
+  plugins: [],
+  version: {
+    source: 'package.json'
   }
 }
 

package/docs/package.json

@@ -4,14 +4,15 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
+    "copy-docs": "node node_modules/@fjell/docs-template/scripts/copy-docs.js",
+    "dev": "npm run copy-docs && vite",
+    "build": "npm run copy-docs && tsc && vite build",
     "preview": "vite preview",
     "test": "vitest run --coverage",
     "test:watch": "vitest --watch"
   },
   "dependencies": {
-    "@fjell/docs-template": "^1.0.4",
+    "@fjell/docs-template": "^1.0.5",
     "react": "^19.1.0",
     "react-dom": "^19.1.0"
   },
@@ -22,12 +23,12 @@
     "@types/react": "^19.1.8",
     "@types/react-dom": "^19.1.6",
     "@types/react-syntax-highlighter": "^15.5.13",
-    "@vitejs/plugin-react": "^4.6.0",
+    "@vitejs/plugin-react": "^4.7.0",
     "@vitest/coverage-v8": "^3.2.4",
     "@vitest/ui": "^3.2.4",
     "jsdom": "^26.1.0",
     "typescript": "^5.8.3",
-    "vite": "^7.0.0",
+    "vite": "^7.0.5",
     "vitest": "^3.2.4"
   }
 }

package/docs/public/GETTING_STARTED.md

@@ -0,0 +1,69 @@
+# 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/docs/public/api.md

@@ -1,527 +1,62 @@
-# Fjell Core API Reference
+# API Reference
 
-Complete API documentation for all Fjell Core modules and utilities.
+Complete Registry API documentation and method reference.
 
-## Overview
-
-Fjell Core provides essential item management, key utilities, and service coordination for the entire Fjell ecosystem. This reference covers all public APIs, interfaces, and utilities.
-
-## Core Modules
-
-### IFactory - Item Factory
-
-The IFactory provides type-safe item creation with validation and configuration support.
-
-#### Methods
-
-##### `create<T>(type: string, data: Partial<T>): T`
-
-Creates a new item of the specified type with type safety.
-
-**Parameters:**
-- `type` - String identifier for the item type
-- `data` - Partial item data to initialize the item
-
-**Returns:** Fully constructed item of type T
-
-**Example:**
-```typescript
-import { IFactory } from '@fjell/core'
-
-interface User {
-  id: string
-  name: string
-  email: string
-}
-
-const user = IFactory.create<User>('user', {
-  id: 'user-123',
-  name: 'John Doe',
-  email: 'john@example.com'
-})
-```
-
-##### `createWithDefaults<T>(type: string, data: Partial<T>, defaults: Partial<T>): T`
-
-Creates an item with default values applied when properties are missing.
-
-**Parameters:**
-- `type` - String identifier for the item type
-- `data` - Partial item data
-- `defaults` - Default values to apply for missing properties
-
-**Returns:** Constructed item with defaults applied
-
----
-
-### KUtils - Key Utilities
-
-Utilities for hierarchical key generation, parsing, and manipulation.
-
-#### Methods
-
-##### `generateKey(components: string[]): string`
-
-Generates a hierarchical key from an array of components.
-
-**Parameters:**
-- `components` - Array of string components to join
-
-**Returns:** Generated key string with proper separators
-
-**Example:**
-```typescript
-import { KUtils } from '@fjell/core'
-
-const userKey = KUtils.generateKey(['users', 'user-123'])
-// Returns: "users:user-123"
-
-const profileKey = KUtils.generateKey(['users', 'user-123', 'profile'])
-// Returns: "users:user-123:profile"
-```
-
-##### `parseKey(key: string): string[]`
-
-Parses a hierarchical key back into its component parts.
-
-**Parameters:**
-- `key` - Key string to parse
-
-**Returns:** Array of key components
-
-**Example:**
-```typescript
-const components = KUtils.parseKey('users:user-123:profile')
-// Returns: ['users', 'user-123', 'profile']
-```
-
-##### `isValidKey(key: string): boolean`
-
-Validates whether a key is properly formatted according to Fjell standards.
-
-**Parameters:**
-- `key` - Key string to validate
-
-**Returns:** Boolean indicating if the key is valid
-
-##### `getParentKey(key: string): string | null`
-
-Gets the parent key by removing the last component.
-
-**Parameters:**
-- `key` - Child key
-
-**Returns:** Parent key string or null if no parent exists
-
-**Example:**
-```typescript
-const parentKey = KUtils.getParentKey('users:user-123:profile')
-// Returns: "users:user-123"
-```
-
----
-
-### AItemService - Abstract Service Base
-
-Abstract base class for building domain-specific services with common patterns.
-
-#### Properties
-
-##### `logger: Logger`
-Logger instance for the service (when logging is configured).
-
-#### Methods
-
-##### `validate<T>(item: T): Promise<void>`
-
-Validates an item according to service-specific rules. Override in subclasses.
-
-**Parameters:**
-- `item` - Item to validate
-
-**Throws:** ValidationError if validation fails
-
-##### `save<T>(item: T): Promise<T>`
-
-Saves an item to the underlying storage. Override in subclasses.
-
-**Parameters:**
-- `item` - Item to save
-
-**Returns:** Promise resolving to the saved item
-
-##### `findById<T>(id: string): Promise<T | null>`
-
-Finds an item by its identifier. Override in subclasses.
-
-**Parameters:**
-- `id` - Item identifier
-
-**Returns:** Promise resolving to the found item or null
-
-##### `delete(id: string): Promise<void>`
-
-Deletes an item by its identifier. Override in subclasses.
-
-**Parameters:**
-- `id` - Item identifier to delete
-
-**Example:**
-```typescript
-import { AItemService, IFactory } from '@fjell/core'
-
-class UserService extends AItemService {
-  private users = new Map<string, User>()
-
-  async save<User>(user: User): Promise<User> {
-    // Custom save logic
-    this.users.set(user.id, user)
-    return user
-  }
-
-  async findById(id: string): Promise<User | null> {
-    return this.users.get(id) || null
-  }
-
-  async validate(user: User): Promise<void> {
-    if (!user.email?.includes('@')) {
-      throw new Error('Valid email required')
-    }
-  }
-}
-```
-
----
-
-### IQFactory - Query Factory
-
-Factory for building complex queries for data retrieval.
-
-#### Methods
-
-##### `create(type: string): QueryBuilder`
-
-Creates a new query builder for the specified entity type.
-
-**Parameters:**
-- `type` - Entity type to query
-
-**Returns:** QueryBuilder instance for method chaining
-
-**Example:**
-```typescript
-import { IQFactory } from '@fjell/core'
-
-const query = IQFactory.create('user')
-  .where('status', 'active')
-  .where('age', '>', 18)
-  .orderBy('createdAt', 'desc')
-  .limit(10)
-```
-
----
-
-### QueryBuilder
-
-Fluent interface for constructing queries with filters, sorting, and pagination.
-
-#### Methods
-
-##### `where(field: string, value: any): QueryBuilder`
-##### `where(field: string, operator: string, value: any): QueryBuilder`
-
-Adds a where condition to the query.
-
-**Parameters:**
-- `field` - Field name to filter on
-- `operator` - Comparison operator ('=', '>', '<', '>=', '<=', '!=', 'like', 'in')
-- `value` - Value to compare against
-
-**Returns:** QueryBuilder for method chaining
-
-##### `orderBy(field: string, direction?: 'asc' | 'desc'): QueryBuilder`
-
-Adds ordering to the query results.
-
-**Parameters:**
-- `field` - Field to order by
-- `direction` - Sort direction (default: 'asc')
-
-**Returns:** QueryBuilder for method chaining
-
-##### `limit(count: number): QueryBuilder`
-
-Limits the number of results returned.
-
-**Parameters:**
-- `count` - Maximum number of results
-
-**Returns:** QueryBuilder for method chaining
-
-##### `offset(count: number): QueryBuilder`
-
-Sets the number of results to skip (for pagination).
-
-**Parameters:**
-- `count` - Number of results to skip
-
-**Returns:** QueryBuilder for method chaining
-
----
-
-### IQUtils - Query Utilities
-
-Utilities for executing and manipulating queries.
-
-#### Methods
-
-##### `execute<T>(query: QueryBuilder): Promise<T[]>`
-
-Executes a query and returns the matching results.
-
-**Parameters:**
-- `query` - Query to execute
-
-**Returns:** Promise resolving to array of matching items
-
-##### `count(query: QueryBuilder): Promise<number>`
-
-Counts the number of results that would be returned by a query.
-
-**Parameters:**
-- `query` - Query to count
-
-**Returns:** Promise resolving to the count
-
-##### `exists(query: QueryBuilder): Promise<boolean>`
-
-Checks if any results exist for the given query.
-
-**Parameters:**
-- `query` - Query to check
-
-**Returns:** Promise resolving to boolean indicating existence
-
----
-
-## Core Interfaces
-
-### Item
-
-Base interface that all items should extend.
-
-```typescript
-interface Item {
-  id: string
-  type?: string
-  createdAt?: string
-  updatedAt?: string
-}
-```
-
-### ServiceConfig
-
-Configuration options for services.
-
-```typescript
-interface ServiceConfig {
-  name: string
-  version?: string
-  logger?: Logger
-  enableMetrics?: boolean
-  timeout?: number
-}
-```
-
-### ValidationResult
-
-Result of item validation operations.
-
-```typescript
-interface ValidationResult {
-  isValid: boolean
-  errors: ValidationError[]
-  warnings?: ValidationWarning[]
-}
-```
-
-### WhereCondition
-
-Represents a query filter condition.
+## Core Registry Interface
 
 ```typescript
-interface WhereCondition {
-  field: string
-  operator: string
-  value: any
+interface Registry {
+  readonly type: string; // Mandatory type identifier
+  createInstance: <...>(...) => Instance<...>;
+  get: (...) => Instance | null;
+  getCoordinates: () => Coordinate[]; // Discover all registered coordinates
+  instanceTree: InstanceTree;
 }
 ```
 
-### OrderByClause
+## Primary Methods
 
-Represents a query ordering specification.
+### `createRegistry(type: string): Registry`
+Creates a new registry with the specified type identifier.
 
-```typescript
-interface OrderByClause {
-  field: string
-  direction: 'asc' | 'desc'
-}
-```
-
----
+### `registry.createInstance(kta, scopes, factory)`
+Registers a new service instance with the given key type array and scopes.
 
-## Error Types
+### `registry.get(kta, options)`
+Retrieves a service instance by key type array and scope options.
 
-### CoreValidationError
+### `registry.getCoordinates(): Coordinate[]`
+Returns all registered coordinates for service discovery and introspection.
 
-Thrown when item validation fails.
+## RegistryHub Interface
 
 ```typescript
-class CoreValidationError extends Error {
-  details: ValidationDetail[]
-  itemType?: string
+interface RegistryHub {
+  registerRegistry: (registry: Registry) => void;
+  get: (registryType: string, kta: string[], options?: GetOptions) => Instance | null;
+  getRegistries: () => Registry[];
+  getAllCoordinates: () => Array<{coordinate: Coordinate, registryType: string}>;
 }
 ```
 
-### CoreNotFoundError
-
-Thrown when a requested item cannot be found.
-
-```typescript
-class CoreNotFoundError extends Error {
-  id: string
-  itemType?: string
-}
-```
-
-### CoreOperationError
-
-Thrown when a core operation fails.
+## Coordinate System
 
 ```typescript
-class CoreOperationError extends Error {
-  operation: string
-  context?: any
+interface Coordinate {
+  kta: string[]; // Key Type Array - hierarchical identifiers
+  scopes: string[]; // Context qualifiers
 }
 ```
 
----
-
-## Usage Patterns
-
-### Repository Pattern
-
-```typescript
-import { AItemService, IFactory, KUtils } from '@fjell/core'
-
-class UserRepository extends AItemService {
-  private storage = new Map<string, User>()
-
-  async create(userData: Partial<User>): Promise<User> {
-    const user = IFactory.create<User>('user', {
-      id: this.generateId(),
-      createdAt: new Date().toISOString(),
-      ...userData
-    })
-
-    await this.validate(user)
-    return this.save(user)
-  }
-
-  async save(user: User): Promise<User> {
-    const key = KUtils.generateKey(['users', user.id])
-    this.storage.set(key, user)
-    return user
-  }
-
-  async findById(id: string): Promise<User | null> {
-    const key = KUtils.generateKey(['users', id])
-    return this.storage.get(key) || null
-  }
-
-  private generateId(): string {
-    return `user-${Date.now()}-${Math.random().toString(36).substr(2, 9)}`
-  }
-}
-```
+## Complete Documentation
 
-### Query Building
-
-```typescript
-import { IQFactory, IQUtils } from '@fjell/core'
-
-// Find active adult users, ordered by creation date
-const activeAdults = await IQUtils.execute(
-  IQFactory.create('user')
-    .where('status', 'active')
-    .where('age', '>=', 18)
-    .orderBy('createdAt', 'desc')
-    .limit(50)
-)
-
-// Check if any admin users exist
-const hasAdmins = await IQUtils.exists(
-  IQFactory.create('user')
-    .where('role', 'admin')
-)
-
-// Count users by status
-const activeCount = await IQUtils.count(
-  IQFactory.create('user')
-    .where('status', 'active')
-)
-```
-
-### Service Composition
-
-```typescript
-class UserManagementService extends AItemService {
-  constructor(
-    private userRepo: UserRepository,
-    private emailService: EmailService,
-    private auditService: AuditService
-  ) {
-    super()
-  }
-
-  async registerUser(userData: Partial<User>): Promise<User> {
-    // Create user
-    const user = await this.userRepo.create(userData)
-
-    // Send welcome email
-    await this.emailService.sendWelcome(user.email)
-
-    // Log the registration
-    await this.auditService.log('user_registered', {
-      userId: user.id,
-      email: user.email
-    })
-
-    return user
-  }
-}
-```
-
----
-
-## Testing Utilities
-
-Fjell Core provides testing utilities to help with unit and integration tests.
-
-### TestUtils
-
-```typescript
-import { TestUtils } from '@fjell/core/testing'
-
-// Create mock instances for testing
-const mockFactory = TestUtils.createMockFactory()
-const mockService = TestUtils.createMockService()
-
-// Test helpers
-expect(TestUtils.isValidKey('users:123')).toBe(true)
-expect(TestUtils.getKeyComponents('users:123:profile')).toEqual(['users', '123', 'profile'])
-```
+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
 
-This API reference provides comprehensive coverage of all Fjell Core functionality. For practical examples and usage patterns, see the Examples section of the documentation.
+The Foundation section serves as the authoritative API reference with full context and examples.

package/docs/public/examples-README.md

@@ -33,6 +33,18 @@ Shows how each key path maps to different implementations via scopes using the r
 
 Perfect for enterprise applications that need clean separation of concerns and organized service architecture.
 
+### 4. `registry-statistics-example.ts` 📊 **Usage Analytics**
+**Track and monitor registry usage patterns with scope-aware analytics!** Demonstrates advanced statistics tracking:
+- **Scope-Aware Tracking**: Separate statistics for each kta + scopes combination
+- **Total Call Monitoring**: Track overall `get()` method usage
+- **Detailed Coordinate Records**: Individual tracking for each service/scope pair
+- **Environment Analysis**: Aggregate statistics by environment (prod/dev)
+- **Most/Least Used Services**: Identify usage patterns and bottlenecks
+- **Immutable Statistics**: Safe access to tracking data without affecting internal state
+- **Normalized Scope Handling**: Consistent tracking regardless of scope order
+
+Perfect for monitoring, optimization, understanding service usage patterns, and analyzing environment-specific behavior in production applications.
+
 ## Key Concepts Demonstrated
 
 ### Simple Usage (simple-example.ts)
@@ -162,9 +174,16 @@ npx tsx examples/coordinates-example.ts
 # Run the RegistryHub cross-registry coordinate discovery example
 npx tsx examples/registry-hub-coordinates-example.ts
 
+# Run the registry statistics tracking example
+npx tsx examples/registry-statistics-example.ts
+
 # Or in Node.js
 node -r esbuild-register examples/simple-example.ts
+node -r esbuild-register examples/multi-level-keys.ts
 node -r esbuild-register examples/registry-hub-types.ts
+node -r esbuild-register examples/coordinates-example.ts
+node -r esbuild-register examples/registry-hub-coordinates-example.ts
+node -r esbuild-register examples/registry-statistics-example.ts
 ```
 
 ## Integration with Real Fjell Registry

package/docs/src/types.d.ts

@@ -1,9 +1,43 @@
+// Types are provided by the @fjell/docs-template package
+
 declare module '@fjell/docs-template' {
-  export * from '../../../fjell-docs-template/src/types'
-  export { DocsApp } from '../../../fjell-docs-template/src/components/DocsApp'
+  export interface DocsConfig {
+    projectName: string;
+    basePath: string;
+    port: number;
+    branding: {
+      theme: string;
+      tagline: string;
+      logo?: string;
+      backgroundImage?: string;
+      primaryColor?: string;
+      accentColor?: string;
+      github?: string;
+      npm?: string;
+    };
+    sections: Array<{
+      id: string;
+      title: string;
+      subtitle: string;
+      file: string;
+    }>;
+    plugins?: any[];
+    version: {
+      source: string;
+    };
+    customContent?: {
+      [key: string]: (content: string) => string;
+    };
+  }
+
+  export interface DocsAppProps {
+    config: DocsConfig;
+  }
+
+  export const DocsApp: React.ComponentType<DocsAppProps>;
 }
 
-declare module '../docs.config.js' {
+declare module '../docs.config.ts' {
   import type { DocsConfig } from '@fjell/docs-template'
   const config: DocsConfig
   export default config

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fjell/registry",
-  "version": "4.4.13",
+  "version": "4.4.16",
   "keywords": [
     "registry",
     "fjell"
@@ -22,7 +22,7 @@
   "type": "module",
   "dependencies": {
     "@fjell/core": "^4.4.13",
-    "@fjell/logging": "^4.4.13",
+    "@fjell/logging": "^4.4.14",
     "deepmerge": "^4.3.1"
   },
   "devDependencies": {
@@ -35,6 +35,7 @@
     "@types/node": "^24.1.0",
     "@typescript-eslint/eslint-plugin": "^8.38.0",
     "@typescript-eslint/parser": "^8.38.0",
+    "@vitejs/plugin-react": "^4.7.0",
     "@vitest/coverage-v8": "^3.2.4",
     "concurrently": "^9.2.0",
     "eslint": "^9.31.0",
@@ -59,6 +60,10 @@
     "clean": "rimraf dist",
     "test": "pnpm run lint && vitest run --coverage",
     "test:memory:optimized": "pnpm run lint && NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=1024\" vitest run tests/memory.test.ts",
-    "test:timing:optimized": "pnpm run lint && NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=1024\" vitest run tests/timing.test.ts"
+    "test:timing:optimized": "pnpm run lint && NODE_OPTIONS=\"--max-old-space-size=8192 --max-semi-space-size=1024\" vitest run tests/timing.test.ts",
+    "docs:dev": "cd docs && pnpm run dev",
+    "docs:build": "cd docs && pnpm run build",
+    "docs:preview": "cd docs && pnpm run preview",
+    "docs:test": "cd docs && pnpm run test"
   }
 }