@northern/yaml-loader 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Luke Schreur
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,1006 @@
+# YAML Loader
+
+A comprehensive utility for loading and parsing YAML/JSON files with advanced `$ref` resolution, type safety, and performance optimizations.
+
+## Install
+
+Install with NPM:
+
+    npm install @northern/di
+
+or Yarn:
+
+    yarn add @northern/di
+
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Basic Usage](#basic-usage)
+- [Type Safety](#type-safety)
+- [Reference Resolution](#reference-resolution)
+- [Configuration Options](#configuration-options)
+- [Error Handling](#error-handling)
+- [Performance Features](#performance-features)
+- [Security Features](#security-features)
+- [Advanced Usage](#advanced-usage)
+- [API Reference](#api-reference)
+- [Migration Guide](#migration-guide)
+- [Troubleshooting](#troubleshooting)
+
+## Overview
+
+The YAML loader module provides:
+
+- **Multi-format support**: YAML and JSON file parsing
+- **Advanced reference resolution**: Internal and external `$ref` resolution with circular detection
+- **Type safety**: Full TypeScript generic support
+- **Performance**: LRU caching and optimized algorithms
+- **Security**: Configurable access controls and path validation
+- **Debugging**: Comprehensive debug information and error reporting
+- **Extensibility**: Custom resolver plugin system
+
+## Installation
+
+```typescript
+import { loadYaml, YamlLoaderBuilder, YamlLoaderError } from './yaml-loader';
+```
+
+## Basic Usage
+
+### Simple YAML Loading
+
+```typescript
+// Basic usage - returns any type
+const config = loadYaml('config.yaml');
+console.log(config.name); // Access properties with basic autocomplete
+```
+
+### Loading JSON Files
+
+```typescript
+// JSON files are supported automatically
+const data = loadYaml('data.json');
+```
+
+### Loading Nested Structures
+
+```typescript
+// Complex nested YAML structures
+const app = loadYaml('app.yaml');
+
+// Access nested properties
+const serverConfig = app.server;
+const dbConfig = app.database;
+```
+
+## Type Safety
+
+### Generic Types
+
+```typescript
+interface AppConfig {
+  name: string;
+  version: number;
+  server: {
+    host: string;
+    port: number;
+    ssl?: boolean;
+  };
+  database: {
+    url: string;
+    pool: {
+      min: number;
+      max: number;
+    };
+  };
+  features: string[];
+}
+
+// Full type inference and compile-time checking
+const config = loadYaml<AppConfig>('app.yaml');
+
+// TypeScript will catch type errors
+const host: string = config.server.host; // ✅ Valid
+const port: string = config.server.port; // ❌ TypeScript error: Type 'number' is not assignable to 'string'
+config.invalidProperty; // ❌ TypeScript error: Property does not exist
+```
+
+### Complex Nested Types
+
+```typescript
+interface User {
+  id: number;
+  name: string;
+  profile: {
+    email: string;
+    avatar?: string;
+  };
+  roles: Array<{
+    name: string;
+    permissions: string[];
+  }>;
+}
+
+interface UsersConfig {
+  users: User[];
+  metadata: {
+    created: Date;
+    version: string;
+    tags: string[];
+  };
+}
+
+const usersConfig = loadYaml<UsersConfig>('users.yaml');
+
+// Full type safety throughout
+usersConfig.users.forEach(user => {
+  console.log(user.profile.email); // ✅ Type-safe access
+  user.roles.forEach(role => {
+    console.log(role.permissions.join(', ')); // ✅ Type-safe array operations
+  });
+});
+```
+
+### Union Types and Discriminated Unions
+
+```typescript
+type DatabaseConfig = 
+  | { type: 'postgres'; host: string; port: number; database: string; }
+  | { type: 'mongodb'; url: string; collection: string; };
+
+interface ServiceConfig {
+  name: string;
+  database: DatabaseConfig;
+}
+
+const config = loadYaml<ServiceConfig>('service.yaml');
+
+// TypeScript will help you handle different database types
+if (config.database.type === 'postgres') {
+  console.log(config.database.host); // ✅ TypeScript knows this is postgres config
+  // config.database.url; // ❌ TypeScript error: Property 'url' does not exist
+}
+```
+
+## Reference Resolution
+
+### Internal References
+
+```yaml
+# config.yaml
+definitions:
+  server:
+    host: localhost
+    port: 3000
+  database:
+    url: postgresql://localhost:5432/mydb
+    
+services:
+  api:
+    # Internal reference to definitions
+    $ref: "#/definitions/server"
+  database:
+    $ref: "#/definitions/database"
+```
+
+```typescript
+const config = loadYaml('config.yaml');
+// Result will have fully resolved structure
+// {
+//   definitions: { server: {...}, database: {...} },
+//   services: {
+//     api: { host: 'localhost', port: 3000 },
+//     database: { url: 'postgresql://localhost:5432/mydb' }
+//   }
+// }
+```
+
+### External File References
+
+```yaml
+# shared/database.yaml
+url: postgresql://localhost:5432/mydb
+pool:
+  min: 5
+  max: 20
+
+# config.yaml
+database:
+  $ref: "./shared/database.yaml"
+  
+api:
+  version: v1
+  port: 8080
+```
+
+### Combined External and Pointer References
+
+```yaml
+# schemas/user.yaml
+definitions:
+  User:
+    type: object
+    properties:
+      id:
+        type: integer
+      name:
+        type: string
+      email:
+        type: string
+        format: email
+
+# api.yaml
+userSchema:
+  $ref: "./schemas/user.yaml#/definitions/User"
+  
+endpoints:
+  - path: /users
+    schema:
+      $ref: "./schemas/user.yaml#/definitions/User"
+```
+
+### Nested Reference Chains
+
+```yaml
+# level3.yaml
+finalValue: "Deeply nested reference resolved"
+
+# level2.yaml
+data:
+  $ref: "./level3.yaml"
+
+# level1.yaml
+nested:
+  $ref: "./level2.yaml"
+
+# main.yaml
+result:
+  $ref: "./level1.yaml"
+```
+
+### Array References
+
+```yaml
+# item.yaml
+type: shared-item
+properties:
+  name: string
+  value: number
+
+# main.yaml
+items:
+  - name: inline1
+    type: local
+  - $ref: "./item.yaml"
+  - name: inline2
+    type: local
+  - $ref: "./item.yaml"
+```
+
+### JSON Pointer Features
+
+```yaml
+# data.yaml
+"a/b path":
+  value: "path with slash"
+"a~b":
+  value: "path with tilde"
+items:
+  - first
+  - second
+  - third
+
+# ref.yaml
+# Reference with escaped characters
+slashExample:
+  $ref: "./data.yaml#/a~1b path"
+tildeExample:
+  $ref: "./data.yaml#/a~0b"
+arrayItem:
+  $ref: "./data.yaml#/items/1"
+```
+
+## Configuration Options
+
+### Basic Configuration
+
+```typescript
+import { YamlLoaderOptions } from './yaml-loader';
+
+const options: YamlLoaderOptions = {
+  maxCacheSize: 50,
+  allowExternalAccess: false,
+  strictMode: true
+};
+
+const config = loadYaml('config.yaml', options);
+```
+
+### Cache Configuration
+
+```typescript
+// Large cache for enterprise applications
+const enterpriseOptions: YamlLoaderOptions = {
+  maxCacheSize: 500 // Cache up to 500 files
+};
+
+// Small cache for simple applications
+const simpleOptions: YamlLoaderOptions = {
+  maxCacheSize: 10 // Cache only 10 files
+};
+```
+
+### Security Configuration
+
+```typescript
+// Default: prevent directory traversal
+const secureOptions: YamlLoaderOptions = {
+  allowExternalAccess: false
+};
+
+// Allow external access for trusted environments
+const openOptions: YamlLoaderOptions = {
+  allowExternalAccess: true
+};
+```
+
+### Strict Mode
+
+```typescript
+// Enable strict validation
+const strictOptions: YamlLoaderOptions = {
+  strictMode: true
+};
+
+// Disable for legacy compatibility
+const lenientOptions: YamlLoaderOptions = {
+  strictMode: false
+};
+```
+
+## Error Handling
+
+### Basic Error Handling
+
+```typescript
+import { YamlLoaderError } from './yaml-loader';
+
+try {
+  const config = loadYaml('config.yaml');
+  console.log('Loaded successfully:', config);
+} catch (error) {
+  if (error instanceof YamlLoaderError) {
+    console.error(`YAML Error (${error.type}): ${error.message}`);
+    if (error.path) {
+      console.error('Path:', error.path);
+    }
+    if (error.refChain) {
+      console.error('Reference chain:', error.refChain.join(' -> '));
+    }
+  } else {
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+### Error Types
+
+```typescript
+// Circular reference error
+try {
+  loadYaml('circular.yaml');
+} catch (error) {
+  if (error instanceof YamlLoaderError && error.type === 'circular_ref') {
+    console.log('Circular reference detected');
+    console.log('Chain:', error.refChain);
+  }
+}
+
+// File not found error
+try {
+  loadYaml('missing.yaml');
+} catch (error) {
+  if (error instanceof YamlLoaderError && error.type === 'file_not_found') {
+    console.log('File not found:', error.path);
+  }
+}
+
+// Invalid JSON pointer
+try {
+  loadYaml('invalid-pointer.yaml');
+} catch (error) {
+  if (error instanceof YamlLoaderError && error.type === 'invalid_pointer') {
+    console.log('Invalid pointer path:', error.path);
+  }
+}
+
+// Parse error
+try {
+  loadYaml('invalid.yaml');
+} catch (error) {
+  if (error instanceof YamlLoaderError && error.type === 'parse_error') {
+    console.log('Parse error:', error.message);
+  }
+}
+```
+
+### Validation Mode
+
+```typescript
+import { validateYamlReferences } from './yaml-loader';
+
+// Validate without full resolution
+const validation = validateYamlReferences('config.yaml');
+
+if (validation.isValid) {
+  console.log('All references are valid');
+  const config = loadYaml('config.yaml');
+} else {
+  console.log('Validation failed:');
+  validation.errors.forEach(error => {
+    console.error(`- ${error.type}: ${error.message}`);
+  });
+  validation.warnings.forEach(warning => {
+    console.warn(`Warning: ${warning}`);
+  });
+}
+```
+
+## Performance Features
+
+### LRU Cache
+
+```typescript
+// Configure cache size based on application needs
+const options: YamlLoaderOptions = {
+  maxCacheSize: 100 // Default: 100 files
+};
+
+// Cache automatically handles:
+// - Most recently used files stay in memory
+// - Least recently used files are evicted when limit reached
+// - Multiple references to same file use cached version
+
+const config = loadYaml('main.yaml', options);
+// If main.yaml references shared.yaml multiple times, it's loaded once
+```
+
+### Debug Mode
+
+```typescript
+import { loadYamlWithDebug } from './yaml-loader';
+
+const { result, debug } = loadYamlWithDebug('complex.yaml');
+
+console.log(`Resolution completed in ${debug.resolutionTime}ms`);
+console.log(`Processed ${debug.refChain.length} references`);
+console.log(`Cached ${debug.fileCache.size} files`);
+
+// Analyze cache contents
+for (const [file, type] of debug.fileCache) {
+  console.log(`${file}: ${type}`);
+}
+```
+
+### Performance Monitoring
+
+```typescript
+// Create a performance wrapper
+function loadWithMetrics<T = any>(filename: string): T {
+  const start = Date.now();
+  const { result, debug } = loadYamlWithDebug(filename);
+  const duration = Date.now() - start;
+  
+  console.log(`Load time: ${duration}ms`);
+  console.log(`Cache hits: ${debug.fileCache.size}`);
+  console.log(`References resolved: ${debug.refChain.length}`);
+  
+  return result;
+}
+
+const config = loadWithMetrics('config.yaml');
+```
+
+## Security Features
+
+### Directory Traversal Protection
+
+```typescript
+// Default: prevents access outside base directory
+const secureConfig = loadYaml('config.yaml');
+// This will fail if config.yaml contains: $ref: "../secret.yaml"
+```
+
+### Allow External Access
+
+```typescript
+// Enable external access for trusted environments
+const options: YamlLoaderOptions = {
+  allowExternalAccess: true
+};
+
+const config = loadYaml('config.yaml', options);
+// Now allows: $ref: "../shared/config.yaml"
+```
+
+### Path Validation
+
+```typescript
+// Custom path validation
+function loadWithValidation(filename: string, allowedPaths: string[]) {
+  try {
+    return loadYaml(filename, { allowExternalAccess: true });
+  } catch (error) {
+    if (error instanceof YamlLoaderError && error.type === 'file_not_found') {
+      // Check if path is in allowed list
+      const isAllowed = allowedPaths.some(path => 
+        error.path?.includes(path)
+      );
+      if (!isAllowed) {
+        throw new Error('Access denied to external file');
+      }
+    }
+    throw error;
+  }
+}
+```
+
+## Advanced Usage
+
+### Builder Pattern
+
+```typescript
+import { YamlLoaderBuilder } from './yaml-loader';
+
+// Simple builder
+const loader = new YamlLoaderBuilder()
+  .withCache(50)
+  .withStrictMode(true)
+  .withExternalAccess(false)
+  .build();
+
+const config = loader('config.yaml');
+
+// Generic builder with type safety
+interface AppConfig {
+  name: string;
+  version: number;
+}
+
+const typedLoader = new YamlLoaderBuilder()
+  .withCache(25)
+  .buildGeneric<AppConfig>();
+
+const appConfig = typedLoader('app.yaml');
+// Full type inference with AppConfig interface
+```
+
+### Custom Resolvers
+
+```typescript
+import { YamlLoaderBuilder } from './yaml-loader';
+
+// Environment variable resolver
+const loader = new YamlLoaderBuilder()
+  .withCustomResolver('env:', (ref) => {
+    const varName = ref.replace('env:', '');
+    return process.env[varName] || '';
+  })
+  .build();
+
+// Usage in YAML:
+# config.yaml
+database:
+  url: env:DATABASE_URL
+  password: env:DB_PASSWORD
+
+const config = loader('config.yaml');
+// config.database.url will contain the environment variable value
+```
+
+### HTTP Resolver
+
+```typescript
+import axios from 'axios';
+
+// HTTP-based resolver for remote schemas
+const httpLoader = new YamlLoaderBuilder()
+  .withCustomResolver('http:', async (ref) => {
+    const response = await axios.get(ref);
+    return response.data;
+  })
+  .withCustomResolver('https:', async (ref) => {
+    const response = await axios.get(ref);
+    return response.data;
+  })
+  .build();
+
+// Usage in YAML:
+# config.yaml
+schema:
+  $ref: "https://example.com/schemas/user.json"
+```
+
+### Template Resolver
+
+```typescript
+// Template-based resolver for dynamic values
+const templateLoader = new YamlLoaderBuilder()
+  .withCustomResolver('template:', (ref) => {
+    const templateName = ref.replace('template:', '');
+    const templates = {
+      'user-service': {
+        port: 3000,
+        endpoints: ['/users', '/users/{id}']
+      },
+      'auth-service': {
+        port: 3001,
+        endpoints: ['/login', '/logout', '/refresh']
+      }
+    };
+    return templates[templateName];
+  })
+  .build();
+
+// Usage in YAML:
+# config.yaml
+userService:
+  $ref: "template:user-service"
+authService:
+  $ref: "template:auth-service"
+```
+
+### Conditional Loading
+
+```typescript
+function loadConfig(configPath: string, isProduction: boolean) {
+  const options: YamlLoaderOptions = {
+    maxCacheSize: isProduction ? 500 : 50,
+    allowExternalAccess: !isProduction,
+    strictMode: isProduction
+  };
+  
+  return loadYaml(configPath, options);
+}
+
+const devConfig = loadConfig('config.yaml', false);
+const prodConfig = loadConfig('config.yaml', true);
+```
+
+### Plugin System
+
+```typescript
+// Create a plugin loader
+interface Plugin {
+  name: string;
+  resolver: (ref: string) => any;
+}
+
+class ExtensibleYamlLoader {
+  private builder = new YamlLoaderBuilder();
+  
+  addPlugin(plugin: Plugin): this {
+    this.builder.withCustomResolver(`${plugin.name}:`, plugin.resolver);
+    return this;
+  }
+  
+  build<T = any>() {
+    return this.builder.buildGeneric<T>();
+  }
+}
+
+// Usage
+const loader = new ExtensibleYamlLoader()
+  .addPlugin({
+    name: 'env',
+    resolver: (ref) => process.env[ref.replace('env:', '')] || ''
+  })
+  .addPlugin({
+    name: 'secret',
+    resolver: (ref) => {
+      // Load from secret manager
+      return getSecret(ref.replace('secret:', ''));
+    }
+  })
+  .build();
+```
+
+## API Reference
+
+### Core Functions
+
+#### `loadYaml<T>(filename: string, options?: YamlLoaderOptions): T`
+
+Loads and parses a YAML file with reference resolution.
+
+**Parameters:**
+- `filename: string` - Absolute path to the YAML/JSON file
+- `options?: YamlLoaderOptions` - Configuration options (optional)
+
+**Returns:**
+- `T` - Parsed and resolved content with type inference
+
+**Example:**
+```typescript
+const config = loadYaml<Config>('config.yaml');
+```
+
+#### `loadYamlWithDebug<T>(filename: string, options?: YamlLoaderOptions): { result: T; debug: DebugInfo }`
+
+Loads YAML with debug information for troubleshooting.
+
+**Returns:**
+- `result: T` - The loaded configuration
+- `debug: DebugInfo` - Debug information including cache stats and timing
+
+#### `validateYamlReferences(filename: string, options?: YamlLoaderOptions): ValidationResult`
+
+Validates references without full resolution.
+
+**Returns:**
+- `isValid: boolean` - Whether all references are valid
+- `errors: YamlLoaderError[]` - List of validation errors
+- `warnings: string[]` - List of warnings
+
+### Classes
+
+#### `YamlLoaderBuilder`
+
+Builder pattern for creating configured loaders.
+
+**Methods:**
+- `withCache(size: number): this` - Set cache size
+- `withStrictMode(enabled: boolean): this` - Enable/disable strict mode
+- `withExternalAccess(enabled: boolean): this` - Allow/deny external access
+- `withCustomResolver(prefix: string, resolver: (ref: string) => any): this` - Add custom resolver
+- `build(): (filename: string) => any` - Build configured loader
+- `buildGeneric<T>(): (filename: string) => T` - Build typed loader
+
+#### `YamlLoaderError`
+
+Enhanced error class for YAML loading issues.
+
+**Properties:**
+- `type: 'circular_ref' | 'file_not_found' | 'invalid_pointer' | 'parse_error'` - Error category
+- `path?: string` - File path or reference path
+- `refChain?: string[]` - Chain of references that led to the error
+
+### Interfaces
+
+#### `YamlLoaderOptions`
+
+Configuration options for YAML loading.
+
+```typescript
+interface YamlLoaderOptions {
+  maxCacheSize?: number;        // Maximum files to cache (default: 100)
+  allowExternalAccess?: boolean; // Allow directory traversal (default: false)
+  customResolvers?: Map<string, (ref: string) => any>; // Custom resolvers
+  strictMode?: boolean;         // Enable strict validation (default: false)
+}
+```
+
+#### `DebugInfo`
+
+Debug information from `loadYamlWithDebug`.
+
+```typescript
+interface DebugInfo {
+  refChain: string[];                    // Reference resolution chain
+  fileCache: Map<string, string>;        // Cached files and their types
+  resolutionTime: number;                 // Time in milliseconds
+}
+```
+
+## Migration Guide
+
+### From Basic Usage
+
+**Before:**
+```typescript
+const yamlLoader = require('./yaml-loader');
+const config = yamlLoader('config.yaml');
+```
+
+**After:**
+```typescript
+import { loadYaml } from './yaml-loader';
+const config = loadYaml('config.yaml');
+```
+
+### Adding Type Safety
+
+**Before:**
+```typescript
+const config = loadYaml('config.yaml');
+// No type checking
+const port = config.port; // Could be anything
+```
+
+**After:**
+```typescript
+interface Config {
+  port: number;
+  host: string;
+}
+const config = loadYaml<Config>('config.yaml');
+const port = config.port; // TypeScript knows it's a number
+```
+
+### Adding Configuration
+
+**Before:**
+```typescript
+const config = loadYaml('config.yaml');
+```
+
+**After:**
+```typescript
+const config = loadYaml('config.yaml', {
+  maxCacheSize: 50,
+  allowExternalAccess: true,
+  strictMode: false
+});
+```
+
+### Using Builder Pattern
+
+**Before:**
+```typescript
+const config = loadYaml('config.yaml');
+```
+
+**After:**
+```typescript
+const loader = new YamlLoaderBuilder()
+  .withCache(50)
+  .withStrictMode(true)
+  .build();
+
+const config = loader('config.yaml');
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### Circular References
+
+**Error:** `Circular reference detected: A -> B -> A`
+
+**Solution:**
+- Check reference chains in YAML files
+- Use `validateYamlReferences()` to detect issues early
+- Consider restructuring to avoid circular dependencies
+
+#### File Not Found
+
+**Error:** `Failed to load file: /path/to/missing.yaml`
+
+**Solutions:**
+- Verify file paths are correct
+- Check if `allowExternalAccess: true` is needed for external files
+- Use absolute paths for reliable resolution
+
+#### Type Errors
+
+**Error:** TypeScript compilation errors
+
+**Solutions:**
+- Define proper interfaces for your YAML structure
+- Use generic type parameter: `loadYaml<MyInterface>()`
+- Check for optional properties with `?` in interfaces
+
+#### Performance Issues
+
+**Symptoms:** Slow loading times
+
+**Solutions:**
+- Increase cache size with `maxCacheSize`
+- Use debug mode to identify bottlenecks
+- Consider simplifying reference chains
+
+### Debug Techniques
+
+#### Using Debug Mode
+
+```typescript
+const { result, debug } = loadYamlWithDebug('complex.yaml');
+
+console.log('Performance Analysis:');
+console.log(`- Total time: ${debug.resolutionTime}ms`);
+console.log(`- References: ${debug.refChain.length}`);
+console.log(`- Cache size: ${debug.fileCache.size}`);
+
+console.log('Reference Chain:');
+debug.refChain.forEach((ref, index) => {
+  console.log(`${index + 1}. ${ref}`);
+});
+```
+
+#### Validation Before Loading
+
+```typescript
+const validation = validateYamlReferences('config.yaml');
+if (!validation.isValid) {
+  console.log('Issues found:');
+  validation.errors.forEach(error => {
+    console.error(`- ${error.type}: ${error.message}`);
+  });
+  return;
+}
+
+// Only load if validation passes
+const config = loadYaml('config.yaml');
+```
+
+#### File Analysis
+
+```typescript
+// Create a file usage analyzer
+function analyzeFileUsage(filename: string) {
+  const { debug } = loadYamlWithDebug(filename);
+  
+  const fileUsage = new Map<string, number>();
+  
+  // Count file usage from reference chain
+  debug.refChain.forEach(ref => {
+    const filePath = ref.split('#')[0];
+    fileUsage.set(filePath, (fileUsage.get(filePath) || 0) + 1);
+  });
+  
+  console.log('File Usage:');
+  for (const [file, count] of fileUsage) {
+    console.log(`${file}: ${count} references`);
+  }
+}
+
+analyzeFileUsage('config.yaml');
+```
+
+### Performance Optimization
+
+#### Cache Tuning
+
+```typescript
+// For small applications
+const smallAppOptions = { maxCacheSize: 10 };
+
+// For medium applications
+const mediumAppOptions = { maxCacheSize: 50 };
+
+// For large applications
+const largeAppOptions = { maxCacheSize: 200 };
+```
+
+#### Reference Optimization
+
+```yaml
+# Instead of many small references
+api:
+  user:
+    $ref: "./schemas/user.yaml"
+  product:
+    $ref: "./schemas/product.yaml"
+  order:
+    $ref: "./schemas/order.yaml"
+
+# Consider consolidating
+api:
+  schemas:
+    $ref: "./schemas/all.yaml"
+```
+
+#### Lazy Loading
+
+```typescript
+// Load only what you need
+function loadSection<T>(filename: string, pointer: string): T {
+  const fullPath = `${filename}#${pointer}`;
+  return loadYaml<T>(fullPath);
+}
+
+const userConfig = loadSection('config.yaml', '#/services/user');
+const dbConfig = loadSection('config.yaml', '#/database');
+```

package/lib/yaml-loader.d.ts

@@ -0,0 +1,53 @@
+export interface YamlNode {
+    $ref?: string;
+    [key: string]: YamlNode | YamlNode[] | string | number | boolean | null | undefined;
+}
+export interface RefResolution {
+    filePath: string;
+    pointer: string;
+    resolved: any;
+}
+export interface YamlLoaderOptions {
+    maxCacheSize?: number;
+    allowExternalAccess?: boolean;
+    customResolvers?: Map<string, (ref: string) => any>;
+    strictMode?: boolean;
+}
+export interface DebugInfo {
+    refChain: string[];
+    fileCache: Map<string, string>;
+    resolutionTime: number;
+}
+export interface ValidationResult {
+    isValid: boolean;
+    errors: YamlLoaderError[];
+    warnings: string[];
+}
+export declare class YamlLoaderError extends Error {
+    readonly type: 'circular_ref' | 'file_not_found' | 'invalid_pointer' | 'parse_error';
+    readonly path?: string | undefined;
+    readonly refChain?: string[] | undefined;
+    constructor(message: string, type: 'circular_ref' | 'file_not_found' | 'invalid_pointer' | 'parse_error', path?: string | undefined, refChain?: string[] | undefined);
+}
+export declare function loadYaml<T = any>(filename: string, options?: YamlLoaderOptions): T;
+export declare function loadYamlWithDebug<T = any>(filename: string, options?: YamlLoaderOptions): {
+    result: T;
+    debug: DebugInfo;
+};
+export declare function validateYamlReferences(filename: string, options?: YamlLoaderOptions): ValidationResult;
+export declare class YamlLoaderBuilder {
+    private options;
+    withCache(size: number): this;
+    withStrictMode(enabled: boolean): this;
+    withExternalAccess(enabled: boolean): this;
+    withCustomResolver(prefix: string, resolver: (ref: string) => any): this;
+    build(): (filename: string) => any;
+    buildGeneric<T = any>(): (filename: string) => T;
+}
+export declare function getTestCacheInterface(filename: string, options?: YamlLoaderOptions): {
+    clear: () => void;
+    size: () => number;
+    has: (key: string) => boolean;
+    getCache: () => Map<string, any>;
+};
+export default loadYaml;

package/lib/yaml-loader.js

@@ -0,0 +1,272 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.YamlLoaderBuilder = exports.YamlLoaderError = void 0;
+exports.loadYaml = loadYaml;
+exports.loadYamlWithDebug = loadYamlWithDebug;
+exports.validateYamlReferences = validateYamlReferences;
+exports.getTestCacheInterface = getTestCacheInterface;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const yaml_1 = require("yaml");
+class YamlLoaderError extends Error {
+    constructor(message, type, path, refChain) {
+        super(message);
+        this.type = type;
+        this.path = path;
+        this.refChain = refChain;
+        this.name = 'YamlLoaderError';
+    }
+}
+exports.YamlLoaderError = YamlLoaderError;
+class LRUFileCache {
+    constructor(maxSize = 100) {
+        this.cache = new Map();
+        this.maxSize = maxSize;
+    }
+    get(key) {
+        const value = this.cache.get(key);
+        if (value !== undefined) {
+            this.cache.delete(key);
+            this.cache.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, value);
+    }
+    has(key) {
+        return this.cache.has(key);
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+    getCache() {
+        return this.cache;
+    }
+}
+const loadFile = (filename) => {
+    const content = (0, fs_1.readFileSync)(filename, 'utf-8');
+    const ext = (0, path_1.extname)(filename).toLowerCase();
+    if (ext === '.json') {
+        return JSON.parse(content);
+    }
+    return (0, yaml_1.parse)(content);
+};
+const resolvePointer = (obj, pointer) => {
+    if (!pointer || pointer === '' || pointer === '/') {
+        return obj;
+    }
+    const parts = pointer.split('/').filter(Boolean);
+    let current = obj;
+    for (const part of parts) {
+        if (current === null || current === undefined || typeof current !== 'object') {
+            throw new YamlLoaderError(`Cannot resolve pointer "${pointer}": path not found`, 'invalid_pointer', pointer);
+        }
+        const decoded = part.replace(/~1/g, '/').replace(/~0/g, '~');
+        current = current[decoded];
+    }
+    return current;
+};
+const resolvePath = (baseDir, filePath, options) => {
+    const resolved = (0, path_1.resolve)(baseDir, filePath);
+    if (!options.allowExternalAccess && !resolved.startsWith(baseDir)) {
+        throw new YamlLoaderError(`Attempted to access file outside base directory: ${filePath}`, 'invalid_pointer', resolved);
+    }
+    return resolved;
+};
+const parseRef = (ref) => {
+    const [filePath, pointer = ''] = ref.split('#');
+    return { filePath, pointer };
+};
+const resolveRefs = (obj, baseDir, context, rootDoc) => {
+    if (obj === null || obj === undefined) {
+        return obj;
+    }
+    if (Array.isArray(obj)) {
+        return obj.map(item => resolveRefs(item, baseDir, context, rootDoc));
+    }
+    if (typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj.$ref && typeof obj.$ref === 'string' && context.options.customResolvers) {
+        for (const [prefix, resolver] of context.options.customResolvers) {
+            if (obj.$ref.startsWith(prefix)) {
+                return resolver(obj.$ref);
+            }
+        }
+    }
+    if (obj.$ref && typeof obj.$ref === 'string') {
+        const { filePath, pointer } = parseRef(obj.$ref);
+        if (filePath) {
+            const resolvedPath = resolvePath(baseDir, filePath, context.options);
+            const refKey = resolvedPath + '#' + pointer;
+            if (context.pathSet.has(refKey)) {
+                throw new YamlLoaderError(`Circular reference detected: ${context.pathChain.join(' -> ')} -> ${refKey}`, 'circular_ref', refKey, [...context.pathChain, refKey]);
+            }
+            context.pathChain.push(refKey);
+            context.pathSet.add(refKey);
+            try {
+                let refContent;
+                if (context.fileCache.has(resolvedPath)) {
+                    refContent = context.fileCache.get(resolvedPath);
+                }
+                else {
+                    try {
+                        refContent = loadFile(resolvedPath);
+                        context.fileCache.set(resolvedPath, refContent);
+                    }
+                    catch (error) {
+                        throw new YamlLoaderError(`Failed to load file: ${resolvedPath}`, 'file_not_found', resolvedPath, context.pathChain);
+                    }
+                }
+                const refBaseDir = (0, path_1.dirname)(resolvedPath);
+                const resolved = resolvePointer(refContent, pointer);
+                return resolveRefs(resolved, refBaseDir, context, refContent);
+            }
+            finally {
+                context.pathChain.pop();
+                context.pathSet.delete(refKey);
+            }
+        }
+        else {
+            if (!rootDoc) {
+                throw new YamlLoaderError(`Cannot resolve internal reference "${obj.$ref}": root document not available`, 'invalid_pointer', obj.$ref, context.pathChain);
+            }
+            const refKey = '#' + pointer;
+            if (context.pathSet.has(refKey)) {
+                throw new YamlLoaderError(`Circular reference detected: ${context.pathChain.join(' -> ')} -> ${refKey}`, 'circular_ref', refKey, [...context.pathChain, refKey]);
+            }
+            context.pathChain.push(refKey);
+            context.pathSet.add(refKey);
+            try {
+                const resolved = resolvePointer(rootDoc, pointer);
+                return resolveRefs(resolved, baseDir, context, rootDoc);
+            }
+            finally {
+                context.pathChain.pop();
+                context.pathSet.delete(refKey);
+            }
+        }
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(obj)) {
+        result[key] = resolveRefs(value, baseDir, context, rootDoc);
+    }
+    return result;
+};
+const createResolutionContext = (options = {}) => {
+    return {
+        pathChain: [],
+        pathSet: new Set(),
+        fileCache: new LRUFileCache(options.maxCacheSize || 100),
+        options: Object.assign({ maxCacheSize: 100, allowExternalAccess: false, strictMode: false, customResolvers: new Map() }, options),
+        startTime: Date.now(),
+    };
+};
+function loadYaml(filename, options) {
+    const context = createResolutionContext(options);
+    try {
+        const content = loadFile(filename);
+        const baseDir = (0, path_1.dirname)(filename);
+        return resolveRefs(content, baseDir, context, content);
+    }
+    catch (error) {
+        if (error instanceof YamlLoaderError) {
+            throw error;
+        }
+        throw new YamlLoaderError(`Failed to parse YAML file: ${error instanceof Error ? error.message : String(error)}`, 'parse_error', filename);
+    }
+}
+function loadYamlWithDebug(filename, options) {
+    const context = createResolutionContext(options);
+    try {
+        const content = loadFile(filename);
+        const baseDir = (0, path_1.dirname)(filename);
+        const result = resolveRefs(content, baseDir, context, content);
+        return {
+            result,
+            debug: {
+                refChain: [...context.pathChain],
+                fileCache: new Map(Array.from(context.fileCache.getCache().entries()).map(([k, v]) => [k, typeof v])),
+                resolutionTime: Date.now() - context.startTime,
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof YamlLoaderError) {
+            throw error;
+        }
+        throw new YamlLoaderError(`Failed to parse YAML file: ${error instanceof Error ? error.message : String(error)}`, 'parse_error', filename);
+    }
+}
+function validateYamlReferences(filename, options) {
+    const errors = [];
+    const warnings = [];
+    try {
+        const context = createResolutionContext(options);
+        const content = loadFile(filename);
+        const baseDir = (0, path_1.dirname)(filename);
+        resolveRefs(content, baseDir, context, content);
+        return { isValid: true, errors, warnings };
+    }
+    catch (error) {
+        if (error instanceof YamlLoaderError) {
+            errors.push(error);
+        }
+        else {
+            errors.push(new YamlLoaderError(`Unexpected error: ${error instanceof Error ? error.message : String(error)}`, 'parse_error', filename));
+        }
+        return { isValid: false, errors, warnings };
+    }
+}
+class YamlLoaderBuilder {
+    constructor() {
+        this.options = {};
+    }
+    withCache(size) {
+        this.options.maxCacheSize = size;
+        return this;
+    }
+    withStrictMode(enabled) {
+        this.options.strictMode = enabled;
+        return this;
+    }
+    withExternalAccess(enabled) {
+        this.options.allowExternalAccess = enabled;
+        return this;
+    }
+    withCustomResolver(prefix, resolver) {
+        if (!this.options.customResolvers) {
+            this.options.customResolvers = new Map();
+        }
+        this.options.customResolvers.set(prefix, resolver);
+        return this;
+    }
+    build() {
+        return (filename) => loadYaml(filename, this.options);
+    }
+    buildGeneric() {
+        return (filename) => loadYaml(filename, this.options);
+    }
+}
+exports.YamlLoaderBuilder = YamlLoaderBuilder;
+function getTestCacheInterface(filename, options) {
+    const context = createResolutionContext(options);
+    loadFile(filename);
+    return {
+        clear: () => context.fileCache.clear(),
+        size: () => context.fileCache.size(),
+        has: (key) => context.fileCache.has(key),
+        getCache: () => context.fileCache.getCache(),
+    };
+}
+exports.default = loadYaml;

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@northern/yaml-loader",
+  "version": "1.0.0",
+  "description": "Load YAML files from fragment sources",
+  "main": "lib/index.js",
+  "files": [
+    "lib/**/*"
+  ],
+  "scripts": {
+    "build": "tsc --removeComments",
+    "test": "jest",
+    "test:watch": "jest --watch --no-coverage",
+    "test:coverage": "jest --coverage",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/northern/yaml-loader.git"
+  },
+  "keywords": [
+    "di",
+    "dependency injection",
+    "inversion of control",
+    "library"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "northern",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/northern/yaml-loader/issues"
+  },
+  "homepage": "https://github.com/northern/yaml-loader#readme",
+  "devDependencies": {
+    "@types/jest": "^29",
+    "@types/uuid": "^9",
+    "@types/yaml": "^1.9.6",
+    "jest": "^29",
+    "ts-jest": "^29",
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "yaml": "^2.8.2"
+  }
+}