http-request-manager 18.15.32 → 18.15.34

package/src/docs/UTILS_README.md

@@ -0,0 +1,1604 @@
+# Utils Service
+
+Comprehensive utility services for common tasks including encryption, headers, path/query building, object merging, and general utilities.
+
+## Table of Contents
+
+1. [UtilsService - General Utilities](#utilsservice---general-utilities)
+2. [Encryption Services](#encryption-services)
+3. [HeadersService](#headersservice)
+4. [PathQueryService](#pathqueryservice)
+5. [ObjectMergerService](#objectmergerservice)
+
+---
+
+## UtilsService - General Utilities
+
+The `UtilsService` provides a collection of utility functions for common tasks.
+
+### Overview
+
+**Features:**
+- ✅ JSON Handling - Safe JSON parsing and stringification
+- ✅ Type Checking - Runtime type validation
+- ✅ Expiration Management - Duration strings to epoch timestamps
+- ✅ Conversions - Base32, binary, and data format conversions
+- ✅ Object Operations - Deep comparison and property access
+- ✅ Time Utilities - Date/time calculations
+
+### JSON Operations
+
+```typescript
+import { UtilsService } from 'http-request-manager';
+
+const utils = inject(UtilsService);
+
+// Safe JSON parsing
+const parsed = utils.stringToJSON('{"name": "John", "age": 30}');
+// Returns: { name: 'John', age: 30 }
+
+// Safe JSON stringification
+const stringified = utils.JSONToString({ name: 'John', age: 30 });
+// Returns: '{"name":"John","age":30}'
+
+// Handle invalid JSON gracefully
+const invalid = utils.stringToJSON('invalid json');
+// Returns: null (no exception thrown)
+```
+
+### Type Checking
+
+```typescript
+// Check if value is string
+utils.isString('hello'); // true
+utils.isString(123); // false
+
+// Check if value is object
+utils.isObject({}); // true
+utils.isObject([]); // false
+utils.isObject(null); // false
+
+// Check if value is JSON
+utils.isJson('{"valid": true}'); // true
+utils.isJson('invalid'); // false
+
+// Check if object is empty
+utils.isEmpty({}); // true
+utils.isEmpty({ name: 'John' }); // false
+```
+
+### Expiration Management
+
+```typescript
+// Parse duration strings to milliseconds
+utils.parseExpiration('1h'); // 3600000
+utils.parseExpiration('7d'); // 604800000
+utils.parseExpiration('30m'); // 1800000
+utils.parseExpiration('1y'); // 31536000000
+
+// Convert to epoch timestamp
+const expires = utils.calculateExpiresIn('7d');
+// Returns: epoch timestamp 7 days from now
+
+// Check if expired
+const isExpired = utils.isExpired(expires);
+// Returns: true/false
+
+// Get time remaining
+const remaining = utils.getTimeRemaining(expires);
+// Returns: milliseconds until expiration
+```
+
+**Duration Formats:**
+- `'30s'` - 30 seconds
+- `'5m'` - 5 minutes
+- `'1h'` - 1 hour
+- `'1d'` - 1 day
+- `'7d'` - 7 days
+- `'30d'` - 30 days
+- `'1y'` - 1 year
+
+### Conversions
+
+```typescript
+// Base32 to Hex
+const hex = utils.base32ToHex('JBSWY3DPEHPK3PXP');
+
+// Binary to Hex
+const hex = utils.binaryToHex('01001000');
+
+// String to Base64
+const base64 = utils.stringToBase64('Hello World');
+
+// Base64 to String
+const str = utils.base64ToString('SGVsbG8gV29ybGQ=');
+```
+
+### Object Operations
+
+```typescript
+// Deep compare objects
+const areEqual = utils.isObjectEqual(obj1, obj2);
+
+// Get nested property safely
+const value = utils.getProperty(obj, 'user.address.city');
+// Returns: undefined instead of throwing error
+
+// Set nested property
+utils.setProperty(obj, 'user.address.city', 'New York');
+```
+
+### Time Utilities
+
+```typescript
+// Get current epoch time
+const now = utils.getCurrentEpoch();
+
+// Format date
+const formatted = utils.formatDate(new Date(), 'YYYY-MM-DD');
+
+// Calculate date difference
+const diff = utils.getDateDifference(date1, date2, 'days');
+```
+
+---
+
+## Encryption Services
+
+### SymmetricalEncryptionService
+
+AES symmetric encryption for fast data encryption.
+
+**Features:**
+- 🔐 AES-256 encryption
+- 🔑 Automatic key generation
+- 📦 Ideal for data at rest
+- ⚡ Fast encryption/decryption
+
+**Usage:**
+
+```typescript
+import { SymmetricalEncryptionService } from 'http-request-manager';
+
+const encryption = inject(SymmetricalEncryptionService);
+
+// Encrypt data
+const encrypted = encryption.encrypt('Sensitive data');
+console.log('Encrypted:', encrypted);
+
+// Decrypt data
+const decrypted = encryption.decrypt(encrypted);
+console.log('Decrypted:', decrypted);
+
+// Generate encryption key
+const key = encryption.generateKey();
+```
+
+**Methods:**
+```typescript
+encrypt(data: string): string
+decrypt(encryptedData: string): string
+generateKey(): string
+```
+
+### AsymmetricalEncryptionService
+
+RSA asymmetric encryption with public/private key pairs.
+
+**Features:**
+- 🔑 Public/private key encryption
+- ✍️ Digital signatures
+- 🔒 Enhanced security
+- 📜 Key pair generation
+
+**Usage:**
+
+```typescript
+import { AsymmetricalEncryptionService } from 'http-request-manager';
+
+const encryption = inject(AsymmetricalEncryptionService);
+
+// Generate key pair
+const keyPair = encryption.generateKeyPair();
+console.log('Public Key:', keyPair.publicKey);
+console.log('Private Key:', keyPair.privateKey);
+
+// Encrypt with public key
+const encrypted = encryption.encryptWithPublicKey(
+  'Secret message',
+  keyPair.publicKey
+);
+
+// Decrypt with private key
+const decrypted = encryption.decryptWithPrivateKey(
+  encrypted,
+  keyPair.privateKey
+);
+
+// Sign data
+const signature = encryption.sign('Data to sign', keyPair.privateKey);
+
+// Verify signature
+const isValid = encryption.verify(
+  signature,
+  'Data to sign',
+  keyPair.publicKey
+);
+```
+
+**Methods:**
+```typescript
+generateKeyPair(): { publicKey: string, privateKey: string }
+encryptWithPublicKey(data: string, publicKey: string): string
+decryptWithPrivateKey(encryptedData: string, privateKey: string): string
+sign(data: string, privateKey: string): string
+verify(signature: string, data: string, publicKey: string): boolean
+```
+
+### Random Utility
+
+Cryptographically secure random value generation.
+
+**Usage:**
+
+```typescript
+import { Random } from 'http-request-manager';
+
+// Generate random string
+const randomString = Random.generate(16);
+// Example: 'a3f8b2c1d4e5f6g7'
+
+// Generate random number
+const randomNumber = Random.number(1, 100);
+// Example: 42
+
+// Generate random color
+const randomColor = Random.color();
+// Example: '#a3f129'
+
+// Generate UUID
+const uuid = Random.uuid();
+// Example: '550e8400-e29b-41d4-a716-446655440000'
+```
+
+**Methods:**
+```typescript
+generate(length: number): string
+number(min: number, max: number): number
+color(): string
+uuid(): string
+```
+
+---
+
+## HeadersService
+
+Dynamic HTTP header management.
+
+**Features:**
+- 📝 Content-Type management
+- 🌐 Accept-Language with locale
+- 📅 Current-Date header
+- 🔄 Dynamic updates
+
+**Usage:**
+
+```typescript
+import { HeadersService } from 'http-request-manager';
+
+const headersService = inject(HeadersService);
+
+// Get default headers
+const headers = headersService.getDefaultHeaders();
+// {
+//   'Content-Type': 'application/json',
+//   'Accept-Language': 'en-CA',
+//   'Current-Date': '2026-03-28'
+// }
+
+// Get specific header
+const contentType = headersService.getHeader('Content-Type');
+
+// Set custom header
+headersService.setHeader('Authorization', 'Bearer token');
+
+// Remove header
+headersService.removeHeader('Current-Date');
+
+// Get all headers
+const allHeaders = headersService.getAllHeaders();
+```
+
+**Methods:**
+```typescript
+getDefaultHeaders(): { [key: string]: string }
+getHeader(name: string): string | undefined
+setHeader(name: string, value: string): void
+removeHeader(name: string): void
+getAllHeaders(): { [key: string]: string }
+getLanguageHeader(): string
+getDateHeader(): string
+```
+
+**Automatic Language Detection:**
+
+The service automatically detects the current language from `@ngx-translate/core`:
+
+```typescript
+// If current language is 'en'
+headersService.getLanguageHeader();
+// Returns: 'en-CA'
+
+// If current language is 'fr'
+headersService.getLanguageHeader();
+// Returns: 'fr-CA'
+```
+
+---
+
+## PathQueryService
+
+URL path and query parameter building.
+
+**Features:**
+- 🔗 Path segment joining
+- ❓ Query parameter building
+- 🔍 Query string parsing
+- 📝 URL normalization
+
+**Usage:**
+
+```typescript
+import { PathQueryService } from 'http-request-manager';
+
+const pathQuery = inject(PathQueryService);
+
+// Build path from segments
+const path = pathQuery.buildPath(['api', 'users', 123]);
+// Returns: 'api/users/123'
+
+// Build query string
+const queryString = pathQuery.buildQuery({
+  page: 1,
+  limit: 10,
+  filter: 'active'
+});
+// Returns: '?page=1&limit=10&filter=active'
+
+// Parse query string
+const params = pathQuery.parseQuery('?page=1&limit=10');
+// Returns: { page: 1, limit: 10 }
+
+// Join path with query
+const fullUrl = pathQuery.buildUrl('api/users', { page: 1 });
+// Returns: 'api/users?page=1'
+
+// Normalize path
+const normalized = pathQuery.normalizePath('api//users///123');
+// Returns: 'api/users/123'
+```
+
+**Methods:**
+```typescript
+buildPath(segments: any[]): string
+buildQuery(params: { [key: string]: any }): string
+parseQuery(queryString: string): { [key: string]: any }
+buildUrl(path: string, params?: { [key: string]: any }): string
+normalizePath(path: string): string
+```
+
+---
+
+## ObjectMergerService
+
+Deep object merging with advanced options.
+
+**Features:**
+- 🔀 Deep merge objects
+- 📦 Array merging options
+- 🎯 Custom merge strategies
+- 🛡️ Clone protection
+
+**Usage:**
+
+```typescript
+import { ObjectMergerService } from 'http-request-manager';
+
+const merger = inject(ObjectMergerService);
+
+// Basic deep merge
+const merged = merger.deepMerge(obj1, obj2);
+
+// Merge with options
+const mergedWithOptions = merger.deepMerge(obj1, obj2, {
+  clone: true,        // Don't mutate original objects
+  mergeArrays: false  // Replace arrays instead of merging
+});
+
+// Custom merge strategy
+const customMerged = merger.deepMerge(obj1, obj2, {
+  customMerge: (key, targetValue, sourceValue) => {
+    if (key === 'price') {
+      return Math.max(targetValue, sourceValue);
+    }
+    return undefined; // Use default merge
+  }
+});
+```
+
+**MergeOptions:**
+```typescript
+interface MergeOptions {
+  clone?: boolean;              // Clone source objects
+  mergeArrays?: boolean;        // Merge arrays vs replace
+  customMerge?: (key: string, target: any, source: any) => any;
+}
+```
+
+**Example:**
+
+```typescript
+const user1 = {
+  id: 1,
+  name: 'John',
+  preferences: {
+    theme: 'light',
+    notifications: true
+  },
+  tags: ['admin', 'user']
+};
+
+const user2 = {
+  name: 'John Doe',
+  preferences: {
+    language: 'en'
+  },
+  tags: ['moderator']
+};
+
+// Deep merge
+const merged = merger.deepMerge(user1, user2);
+// {
+//   id: 1,
+//   name: 'John Doe',
+//   preferences: {
+//     theme: 'light',
+//     notifications: true,
+//     language: 'en'
+//   },
+//   tags: ['admin', 'user', 'moderator']
+// }
+```
+
+**Methods:**
+```typescript
+deepMerge<T>(target: T, source: Partial<T>, options?: MergeOptions): T
+shallowMerge<T>(target: T, source: Partial<T>): T
+mergeArray<T>(target: T[], source: T[]): T[]
+```
+
+---
+
+## AppService
+
+Application-level utilities.
+
+**Features:**
+- 📱 App ID management
+- 🔍 Environment detection
+- 📊 Logging utilities
+
+**Usage:**
+
+```typescript
+import { AppService } from 'http-request-manager';
+
+const appService = inject(AppService);
+
+// Get app ID
+const appId = appService.getAppId();
+
+// Check environment
+const isProduction = appService.isProduction();
+const isDevelopment = appService.isDevelopment();
+
+// Log with app context
+appService.log('Info message', { data: 'value' });
+appService.warn('Warning message');
+appService.error('Error message');
+```
+
+---
+
+## Related Documentation
+
+- [`Encryption Guide`](ENCRYPTION_README.md) - Detailed encryption documentation
+- [`Models Guide`](MODELS_README.md) - Configuration models
+- [`LocalStorage`](LOCAL_STORAGE_README.md) - Encrypted storage usage
+- [`Interceptors`](INTERCEPTOR_README.md) - Header interceptor details
+  }
+
+  checkTypes() {
+    this.typeResult = {
+      isString: this.utils.isString(this.testValue),
+      isObject: this.utils.isObject(this.testValue),
+      isJson: this.utils.isJSON(this.testValue)
+    };
+  }
+
+  testExpiration() {
+    const oneDayFromNow = this.utils.expires('1d');
+    const currentTime = Math.floor(Date.now() / 1000);
+    
+    this.expiryResult = {
+      oneDay: oneDayFromNow ? new Date(oneDayFromNow * 1000) : null,
+      current: new Date(currentTime * 1000),
+      hasExpired: this.utils.hasExpired(oneDayFromNow || 0),
+      timeRemaining: this.utils.expiresIn(oneDayFromNow || 0)
+    };
+  }
+
+  testConversions() {
+    this.conversionResult = {
+      base32ToHex: this.utils.base32ToHex('JBSWY3DPEHPK3PXP'),
+      binaryToHex: this.utils.binaryToHex('11000011100011110000')
+    };
+  }
+}
+```
+
+## API Reference
+
+### JSON Operations
+
+#### JSONToString(value: any): string
+
+Safely convert value to JSON string:
+
+```typescript
+const obj = { name: 'John', age: 30 };
+const jsonString = this.utils.JSONToString(obj);
+// Returns: '{"name":"John","age":30}'
+
+const number = 42;
+const stringValue = this.utils.JSONToString(number);
+// Returns: '42'
+```
+
+#### stringToJSON(value: string): any
+
+Safely parse JSON string:
+
+```typescript
+const jsonString = '{"name":"John","age":30}';
+const obj = this.utils.stringToJSON(jsonString);
+// Returns: { name: 'John', age: 30 }
+
+const invalidJson = '{invalid json}';
+const result = this.utils.stringToJSON(invalidJson);
+// Returns: '{invalid json}' (unchanged)
+```
+
+### Type Checking
+
+#### isString(value: any): boolean
+
+Check if value is a string:
+
+```typescript
+this.utils.isString('hello');        // true
+this.utils.isString(123);            // false
+this.utils.isString(null);           // false
+this.utils.isString(undefined);      // false
+```
+
+#### isObject(value: any): boolean
+
+Check if value is an object:
+
+```typescript
+this.utils.isObject({});             // true
+this.utils.isObject({ name: 'John' }); // true
+this.utils.isObject(null);           // false
+this.utils.isObject([]);             // true (arrays are objects)
+this.utils.isObject('string');       // false
+```
+
+#### isJSON(value: any): boolean
+
+Check if value is valid JSON:
+
+```typescript
+this.utils.isJSON('{"name":"John"}'); // true
+this.utils.isJSON('not json');        // false
+this.utils.isJSON(123);               // false
+this.utils.isJSON(null);              // false
+```
+
+### Property Access
+
+#### getValueByProp(obj: any, prop: string): any
+
+Get property value by string path:
+
+```typescript
+const obj = { user: { name: 'John', settings: { theme: 'dark' } } };
+
+this.utils.getValueByProp(obj, 'user.name');           // undefined (doesn't support nesting)
+this.utils.getValueByProp(obj.user, 'name');           // 'John'
+this.utils.getValueByProp(obj.user.settings, 'theme'); // 'dark'
+this.utils.getValueByProp(obj, 'nonexistent');         // false
+```
+
+### Object Comparison
+
+#### objectsEqual(x: any, y: any): boolean
+
+Deep comparison of two objects:
+
+```typescript
+const obj1 = { name: 'John', age: 30, active: true };
+const obj2 = { name: 'John', age: 30, active: true };
+const obj3 = { name: 'John', age: 31, active: true };
+
+this.utils.objectsEqual(obj1, obj2); // true
+this.utils.objectsEqual(obj1, obj3); // false
+
+// Nested objects
+const nested1 = { user: { name: 'John', settings: { theme: 'dark' } } };
+const nested2 = { user: { name: 'John', settings: { theme: 'dark' } } };
+this.utils.objectsEqual(nested1, nested2); // true
+```
+
+### HTTP Operations
+
+#### getJSON(file: string): Observable<any>
+
+Get JSON file from assets:
+
+```typescript
+this.utils.getJSON('data/config.json').subscribe(config => {
+  console.log('Config loaded:', config);
+});
+```
+
+### Time Properties
+
+#### today: number
+
+Get current time in milliseconds:
+
+```typescript
+const currentTime = this.utils.today;
+console.log('Current time (ms):', currentTime);
+```
+
+### Expiration Management
+
+#### expires(str?: string): number | undefined
+
+Convert duration string to epoch timestamp:
+
+```typescript
+// Time units: y=years, m=months, w=weeks, d=days, hr=hours, mn=minutes, s=seconds
+
+this.utils.expires('1d');   // Current time + 1 day
+this.utils.expires('2h');   // Current time + 2 hours
+this.utils.expires('30m');  // Current time + 30 minutes
+this.utils.expires('1w');   // Current time + 1 week
+this.utils.expires('1y');   // Current time + 1 year
+
+this.utils.expires();       // undefined (no duration provided)
+```
+
+#### hasExpired(expiryDate: number): boolean
+
+Check if timestamp has expired:
+
+```typescript
+const futureTime = this.utils.expires('1d');
+const pastTime = Math.floor(Date.now() / 1000) - 3600; // 1 hour ago
+
+this.utils.hasExpired(futureTime); // false
+this.utils.hasExpired(pastTime);   // true
+```
+
+#### hasExpiry(setting: any): boolean
+
+Check if setting has expiration:
+
+```typescript
+const setting1 = { expires: 1234567890 };
+const setting2 = { encrypted: true };
+
+this.utils.hasExpiry(setting1); // true
+this.utils.hasExpiry(setting2); // false
+```
+
+#### expiresIn(expiryDate: number): string | undefined
+
+Get human-readable time remaining:
+
+```typescript
+const oneDayFromNow = this.utils.expires('1d');
+const oneHourFromNow = this.utils.expires('1h');
+
+console.log(this.utils.expiresIn(oneDayFromNow));   // "1d"
+console.log(this.utils.expiresIn(oneHourFromNow));  // "1h"
+
+// For expired dates
+const pastTime = Math.floor(Date.now() / 1000) - 3600;
+console.log(this.utils.expiresIn(pastTime));        // "Expired"
+```
+
+### Conversions
+
+#### base32ToHex(base32: string): string
+
+Convert Base32 string to hexadecimal:
+
+```typescript
+this.utils.base32ToHex('JBSWY3DPEHPK3PXP'); // '48656C6C6F20576F726C64'
+this.utils.base32ToHex('MY');               // '66'
+this.utils.base32ToHex('MZXQ6===');         // '6C'
+```
+
+#### binaryToHex(binary: string): string
+
+Convert binary string to hexadecimal:
+
+```typescript
+this.utils.binaryToHex('11000011100011110000'); // 'C78F0'
+this.utils.binaryToHex('10101010');             // 'AA000000'
+this.utils.binaryToHex('1111');                 // 'F000'
+```
+
+### String Utilities
+
+#### lc(str: string): string
+
+Convert string to lowercase with special character replacement:
+
+```typescript
+this.utils.lc('Hello World!');        // 'helloworld'
+this.utils.lc('Test-Case_String');    // 'testcasestring'
+this.utils.lc('UPPER CASE');          // 'uppercase'
+```
+
+## Advanced Examples
+
+### Data Validation Service
+
+```typescript
+import { Injectable } from '@angular/core';
+import { UtilsService } from 'http-request-manager';
+
+interface ValidationResult {
+  isValid: boolean;
+  errors: string[];
+  sanitizedData?: any;
+}
+
+@Injectable({
+  providedIn: 'root'
+})
+export class DataValidationService {
+  constructor(private utils: UtilsService) {}
+
+  validateAndSanitize<T>(data: any, schema: any): ValidationResult {
+    const errors: string[] = [];
+    let sanitizedData: any = {};
+
+    try {
+      // Check if data is object
+      if (!this.utils.isObject(data)) {
+        errors.push('Data must be an object');
+        return { isValid: false, errors };
+      }
+
+      // Sanitize each field according to schema
+      for (const [field, rules] of Object.entries(schema)) {
+        const value = data[field];
+        const sanitizedValue = this.sanitizeField(field, value, rules as any);
+        
+        if (sanitizedValue !== undefined) {
+          sanitizedData[field] = sanitizedValue;
+        }
+      }
+
+      return {
+        isValid: errors.length === 0,
+        errors,
+        sanitizedData
+      };
+    } catch (error) {
+      errors.push(`Validation error: ${error}`);
+      return { isValid: false, errors };
+    }
+  }
+
+  private sanitizeField(field: string, value: any, rules: any): any {
+    // Handle required fields
+    if (rules.required && (value === undefined || value === null)) {
+      throw new Error(`Field '${field}' is required`);
+    }
+
+    if (value === undefined || value === null) {
+      return rules.default;
+    }
+
+    // Type validation
+    switch (rules.type) {
+      case 'string':
+        if (typeof value !== 'string') {
+          throw new Error(`Field '${field}' must be a string`);
+        }
+        break;
+      
+      case 'number':
+        if (typeof value !== 'number' && isNaN(Number(value))) {
+          throw new Error(`Field '${field}' must be a number`);
+        }
+        value = Number(value);
+        break;
+      
+      case 'boolean':
+        if (typeof value !== 'boolean') {
+          throw new Error(`Field '${field}' must be a boolean`);
+        }
+        break;
+      
+      case 'object':
+        if (!this.utils.isObject(value)) {
+          throw new Error(`Field '${field}' must be an object`);
+        }
+        break;
+      
+      case 'json':
+        if (!this.utils.isJSON(value)) {
+          throw new Error(`Field '${field}' must be valid JSON`);
+        }
+        value = this.utils.stringToJSON(value);
+        break;
+    }
+
+    // String-specific rules
+    if (rules.type === 'string') {
+      // Min/max length
+      if (rules.minLength && value.length < rules.minLength) {
+        throw new Error(`Field '${field}' must be at least ${rules.minLength} characters`);
+      }
+      if (rules.maxLength && value.length > rules.maxLength) {
+        throw new Error(`Field '${field}' must be no more than ${rules.maxLength} characters`);
+      }
+
+      // Pattern matching
+      if (rules.pattern && !rules.pattern.test(value)) {
+        throw new Error(`Field '${field}' does not match required pattern`);
+      }
+
+      // Sanitization
+      if (rules.lowercase) {
+        value = value.toLowerCase();
+      }
+      if (rules.trim) {
+        value = value.trim();
+      }
+    }
+
+    // Number-specific rules
+    if (rules.type === 'number') {
+      if (rules.min !== undefined && value < rules.min) {
+        throw new Error(`Field '${field}' must be at least ${rules.min}`);
+      }
+      if (rules.max !== undefined && value > rules.max) {
+        throw new Error(`Field '${field}' must be no more than ${rules.max}`);
+      }
+    }
+
+    // Array-specific rules
+    if (rules.type === 'array') {
+      if (!Array.isArray(value)) {
+        throw new Error(`Field '${field}' must be an array`);
+      }
+      if (rules.minItems && value.length < rules.minItems) {
+        throw new Error(`Field '${field}' must have at least ${rules.minItems} items`);
+      }
+      if (rules.maxItems && value.length > rules.maxItems) {
+        throw new Error(`Field '${field}' must have no more than ${rules.maxItems} items`);
+      }
+    }
+
+    return value;
+  }
+
+  // Predefined schemas
+  getUserSchema() {
+    return {
+      name: {
+        type: 'string',
+        required: true,
+        minLength: 2,
+        maxLength: 50,
+        pattern: /^[a-zA-Z\s]+$/,
+        trim: true
+      },
+      email: {
+        type: 'string',
+        required: true,
+        pattern: /^[^\s@]+@[^\s@]+\.[^\s@]+$/,
+        lowercase: true,
+        trim: true
+      },
+      age: {
+        type: 'number',
+        min: 0,
+        max: 150
+      },
+      preferences: {
+        type: 'object',
+        default: {}
+      }
+    };
+  }
+
+  getProductSchema() {
+    return {
+      name: {
+        type: 'string',
+        required: true,
+        minLength: 1,
+        maxLength: 100
+      },
+      price: {
+        type: 'number',
+        required: true,
+        min: 0
+      },
+      description: {
+        type: 'string',
+        maxLength: 500,
+        trim: true
+      },
+      tags: {
+        type: 'array',
+        maxItems: 10,
+        default: []
+      }
+    };
+  }
+}
+```
+
+### Cache Management Service
+
+```typescript
+@Injectable()
+export class CacheManagerService {
+  constructor(private utils: UtilsService) {}
+
+  createCache<T>(key: string, ttl: string, maxSize?: number) {
+    return {
+      key,
+      ttl: this.utils.expires(ttl),
+      maxSize,
+      data: new Map<string, { value: T; timestamp: number }>(),
+
+      set(itemKey: string, value: T): void {
+        // Clean up expired items
+        this.cleanup();
+
+        // Check size limit
+        if (this.maxSize && this.data.size >= this.maxSize) {
+          // Remove oldest item
+          const oldestKey = this.data.keys().next().value;
+          this.data.delete(oldestKey);
+        }
+
+        this.data.set(itemKey, {
+          value,
+          timestamp: Date.now()
+        });
+      },
+
+      get(itemKey: string): T | null {
+        this.cleanup();
+
+        const item = this.data.get(itemKey);
+        if (item) {
+          return item.value;
+        }
+
+        return null;
+      },
+
+      has(itemKey: string): boolean {
+        this.cleanup();
+        return this.data.has(itemKey);
+      },
+
+      delete(itemKey: string): boolean {
+        return this.data.delete(itemKey);
+      },
+
+      clear(): void {
+        this.data.clear();
+      },
+
+      size(): number {
+        this.cleanup();
+        return this.data.size;
+      },
+
+      cleanup(): void {
+        const now = Date.now();
+        const expiredKeys: string[] = [];
+
+        this.data.forEach((item, key) => {
+          if (item.timestamp < this.ttl * 1000) {
+            expiredKeys.push(key);
+          }
+        });
+
+        expiredKeys.forEach(key => this.data.delete(key));
+      },
+
+      export(): Array<{ key: string; value: T; timestamp: number }> {
+        this.cleanup();
+        return Array.from(this.data.entries()).map(([key, item]) => ({
+          key,
+          value: item.value,
+          timestamp: item.timestamp
+        }));
+      },
+
+      import(items: Array<{ key: string; value: T; timestamp: number }>): void {
+        items.forEach(item => {
+          if (item.timestamp > this.ttl * 1000) {
+            this.data.set(item.key, {
+              value: item.value,
+              timestamp: item.timestamp
+            });
+          }
+        });
+      }
+    };
+  }
+
+  // Global cache instance
+  private globalCache = this.createCache('global-cache', '1h', 100);
+
+  cacheResult<T>(key: string, fn: () => T, ttl: string = '1h'): T {
+    const cached = this.globalCache.get(key);
+    if (cached !== null) {
+      return cached;
+    }
+
+    const result = fn();
+    this.globalCache.set(key, result);
+    return result;
+  }
+
+  invalidateCache(key: string): void {
+    this.globalCache.delete(key);
+  }
+
+  clearCache(): void {
+    this.globalCache.clear();
+  }
+}
+```
+
+### Configuration Manager
+
+```typescript
+@Injectable()
+export class ConfigurationManagerService {
+  private configs = new Map<string, any>();
+
+  constructor(private utils: UtilsService) {}
+
+  loadConfig<T>(configKey: string, defaultValue: T, expiration?: string): T {
+    const cached = this.configs.get(configKey);
+    
+    if (cached && !this.isExpired(cached.timestamp, expiration)) {
+      return cached.value;
+    }
+
+    // Load from storage or API
+    const value = this.loadConfigValue<T>(configKey, defaultValue);
+    
+    this.configs.set(configKey, {
+      value,
+      timestamp: Date.now(),
+      expiresAt: expiration ? this.utils.expires(expiration) : undefined
+    });
+
+    return value;
+  }
+
+  updateConfig<T>(configKey: string, value: T, expiration?: string): void {
+    this.configs.set(configKey, {
+      value,
+      timestamp: Date.now(),
+      expiresAt: expiration ? this.utils.expires(expiration) : undefined
+    });
+
+    this.saveConfigValue(configKey, value);
+  }
+
+  getConfig<T>(configKey: string): T | null {
+    const cached = this.configs.get(configKey);
+    if (cached && !this.isExpired(cached.timestamp, undefined)) {
+      return cached.value;
+    }
+    return null;
+  }
+
+  invalidateConfig(configKey: string): void {
+    this.configs.delete(configKey);
+  }
+
+  clearConfigs(): void {
+    this.configs.clear();
+  }
+
+  private isExpired(timestamp: number, expiration?: string): boolean {
+    if (!expiration) return false;
+    
+    const expiryTime = this.utils.expires(expiration);
+    return this.utils.hasExpired(expiryTime || 0);
+  }
+
+  private loadConfigValue<T>(configKey: string, defaultValue: T): T {
+    try {
+      const stored = localStorage.getItem(`config:${configKey}`);
+      if (stored) {
+        const parsed = JSON.parse(stored);
+        return parsed.value || defaultValue;
+      }
+    } catch (error) {
+      console.warn(`Failed to load config ${configKey}:`, error);
+    }
+    
+    return defaultValue;
+  }
+
+  private saveConfigValue(configKey: string, value: any): void {
+    try {
+      localStorage.setItem(`config:${configKey}`, JSON.stringify({
+        value,
+        savedAt: new Date().toISOString()
+      }));
+    } catch (error) {
+      console.warn(`Failed to save config ${configKey}:`, error);
+    }
+  }
+
+  // Predefined configurations
+  getAppConfig() {
+    return this.loadConfig('app-config', {
+      version: '1.0.0',
+      apiUrl: 'http://localhost:3000',
+      features: {
+        enableAnalytics: true,
+        enableNotifications: true,
+        enableOffline: false
+      },
+      limits: {
+        maxFileSize: 10485760, // 10MB
+        maxRequestsPerMinute: 100
+      }
+    }, '1h');
+  }
+
+  getUserPreferences() {
+    return this.loadConfig('user-preferences', {
+      theme: 'light',
+      language: 'en',
+      notifications: {
+        email: true,
+        push: true,
+        sms: false
+      },
+      privacy: {
+        analytics: true,
+        marketing: false
+      }
+    }, '30d');
+  }
+
+  getFeatureFlags() {
+    return this.loadConfig('feature-flags', {
+      newDashboard: false,
+      darkMode: true,
+      betaFeatures: false,
+      experimentalUI: false
+    }, '1d');
+  }
+}
+```
+
+### URL Parameter Parser
+
+```typescript
+@Injectable()
+export class URLParserService {
+  constructor(private utils: UtilsService) {}
+
+  parseQueryParams(url: string): Record<string, string> {
+    const params: Record<string, string> = {};
+    const queryString = url.split('?')[1];
+    
+    if (!queryString) return params;
+
+    queryString.split('&').forEach(pair => {
+      const [key, value] = pair.split('=');
+      if (key && value) {
+        params[decodeURIComponent(key)] = decodeURIComponent(value);
+      }
+    });
+
+    return params;
+  }
+
+  buildQueryString(params: Record<string, any>): string {
+    const searchParams = new URLSearchParams();
+
+    Object.entries(params).forEach(([key, value]) => {
+      if (value !== null && value !== undefined) {
+        if (Array.isArray(value)) {
+          value.forEach(item => searchParams.append(key, String(item)));
+        } else {
+          searchParams.set(key, String(value));
+        }
+      }
+    });
+
+    return searchParams.toString();
+  }
+
+  extractUrlParams(template: string, actualUrl: string): Record<string, string> {
+    const templateParts = template.split('/');
+    const actualParts = actualUrl.split('/');
+    const params: Record<string, string> = {};
+
+    if (templateParts.length !== actualParts.length) {
+      return params;
+    }
+
+    templateParts.forEach((part, index) => {
+      if (part.startsWith(':')) {
+        const paramName = part.substring(1);
+        params[paramName] = actualParts[index];
+      }
+    });
+
+    return params;
+  }
+
+  buildUrl(template: string, params: Record<string, string>): string {
+    let url = template;
+    
+    Object.entries(params).forEach(([key, value]) => {
+      url = url.replace(`:${key}`, encodeURIComponent(value));
+    });
+
+    return url;
+  }
+
+  // URL validation
+  isValidUrl(url: string): boolean {
+    try {
+      new URL(url);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  isValidEmail(email: string): boolean {
+    const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+    return emailRegex.test(email);
+  }
+
+  sanitizeUrl(url: string): string {
+    // Remove potentially dangerous protocols
+    const dangerousProtocols = ['javascript:', 'data:', 'vbscript:'];
+    
+    dangerousProtocols.forEach(protocol => {
+      if (url.toLowerCase().startsWith(protocol)) {
+        throw new Error(`Dangerous protocol detected: ${protocol}`);
+      }
+    });
+
+    return url;
+  }
+}
+```
+
+## Integration with Other Services
+
+### With HTTP State Service
+
+```typescript
+@Injectable()
+export class SmartCacheService extends HTTPManagerStateService<any> {
+  private utils = inject(UtilsService);
+  private cache = new Map<string, { data: any; expiresAt: number }>();
+
+  constructor() {
+    super(
+      ApiRequest.adapt({ path: ['data'] }),
+      DataType.OBJECT
+    );
+  }
+
+  fetchWithCache(key: string, fetchFn: () => any, ttl: string = '1h') {
+    // Check cache first
+    const cached = this.cache.get(key);
+    if (cached && !this.utils.hasExpired(cached.expiresAt)) {
+      return of(cached.data);
+    }
+
+    // Fetch and cache
+    return fetchFn().pipe(
+      tap(data => {
+        const expiresAt = this.utils.expires(ttl);
+        this.cache.set(key, {
+          data,
+          expiresAt: expiresAt || 0
+        });
+      })
+    );
+  }
+
+  invalidateCache(key: string): void {
+    this.cache.delete(key);
+  }
+
+  clearExpiredCache(): void {
+    const now = Date.now() / 1000;
+    const expiredKeys: string[] = [];
+
+    this.cache.forEach((item, key) => {
+      if (item.expiresAt < now) {
+        expiredKeys.push(key);
+      }
+    });
+
+    expiredKeys.forEach(key => this.cache.delete(key));
+  }
+}
+```
+
+### With Local Storage
+
+```typescript
+@Injectable()
+export class SmartStorageService {
+  private utils = inject(UtilsService);
+  private storage = inject(LocalStorageManagerService);
+
+  setWithExpiration(key: string, value: any, expiration: string): void {
+    const expiresAt = this.utils.expires(expiration);
+    
+    this.storage.setItem(key, {
+      value,
+      expiresAt,
+      createdAt: Date.now()
+    });
+  }
+
+  getWithExpiration<T>(key: string): T | null {
+    const stored = this.storage.getItem(key);
+    
+    if (!stored) return null;
+    
+    if (this.utils.hasExpired(stored.expiresAt)) {
+      this.storage.removeItem(key);
+      return null;
+    }
+    
+    return stored.value;
+  }
+
+  setIfNewer(key: string, value: any, timestamp: number): boolean {
+    const stored = this.storage.getItem(key);
+    
+    if (stored && stored.timestamp > timestamp) {
+      return false; // Stored version is newer
+    }
+    
+    this.storage.setItem(key, {
+      value,
+      timestamp,
+      updatedAt: Date.now()
+    });
+    
+    return true;
+  }
+}
+```
+
+## Best Practices
+
+### 1. Type Safety
+
+```typescript
+// ✅ Good - Validate types before operations
+if (this.utils.isString(value)) {
+  const result = this.utils.lc(value);
+  // Safe to use result as string
+}
+
+// ❌ Avoid - No type checking
+const result = this.utils.lc(value); // Could fail if value is not string
+```
+
+### 2. Error Handling
+
+```typescript
+// ✅ Good - Handle potential errors
+try {
+  const parsed = this.utils.stringToJSON(jsonString);
+  // Process parsed data
+} catch (error) {
+  console.error('Failed to parse JSON:', error);
+  return defaultValue;
+}
+
+// ❌ Avoid - No error handling
+const parsed = this.utils.stringToJSON(jsonString); // Could throw
+```
+
+### 3. Performance Considerations
+
+```typescript
+// ✅ Good - Cache expensive operations
+private cachedBase32Conversion = new Map<string, string>();
+
+convertBase32(value: string): string {
+  if (!this.cachedBase32Conversion.has(value)) {
+    this.cachedBase32Conversion.set(value, this.utils.base32ToHex(value));
+  }
+  return this.cachedBase32Conversion.get(value)!;
+}
+
+// ❌ Avoid - Repeated expensive operations
+// Converting the same value multiple times without caching
+```
+
+### 4. Validation Before Usage
+
+```typescript
+// ✅ Good - Validate input before processing
+validateAndProcess(data: any): any {
+  if (!this.utils.isObject(data)) {
+    throw new Error('Data must be an object');
+  }
+  
+  if (!this.utils.isJSON(JSON.stringify(data))) {
+    throw new Error('Data contains invalid JSON');
+  }
+  
+  return this.processData(data);
+}
+```
+
+## Performance Optimization
+
+### Batch Operations
+
+```typescript
+@Injectable()
+export class BatchUtilsService {
+  private utils = inject(UtilsService);
+
+  batchConvertExpirations(durations: string[]): number[] {
+    return durations.map(duration => this.utils.expires(duration) || 0);
+  }
+
+  batchValidateTypes(values: any[]): Array<{value: any; isString: boolean; isObject: boolean}> {
+    return values.map(value => ({
+      value,
+      isString: this.utils.isString(value),
+      isObject: this.utils.isObject(value)
+    }));
+  }
+
+  batchCompareObjects(pairs: Array<{x: any; y: any}>): boolean[] {
+    return pairs.map(pair => this.utils.objectsEqual(pair.x, pair.y));
+  }
+}
+```
+
+### Memoization
+
+```typescript
+@Injectable()
+export class MemoizedUtilsService {
+  private utils = inject(UtilsService);
+  
+  // Memoization cache
+  private stringToJsonCache = new Map<string, any>();
+  private objectComparisonCache = new Map<string, boolean>();
+
+  memoizedStringToJSON(value: string): any {
+    if (this.stringToJsonCache.has(value)) {
+      return this.stringToJsonCache.get(value);
+    }
+
+    const result = this.utils.stringToJSON(value);
+    this.stringToJsonCache.set(value, result);
+    return result;
+  }
+
+  memoizedObjectsEqual(x: any, y: any): boolean {
+    const key = JSON.stringify([x, y]);
+    
+    if (this.objectComparisonCache.has(key)) {
+      return this.objectComparisonCache.get(key);
+    }
+
+    const result = this.utils.objectsEqual(x, y);
+    this.objectComparisonCache.set(key, result);
+    return result;
+  }
+
+  clearCache(): void {
+    this.stringToJsonCache.clear();
+    this.objectComparisonCache.clear();
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+#### 1. JSON Parsing Errors
+```typescript
+// ✅ Good - Safe JSON parsing
+safeJsonParse(jsonString: string, fallback: any = null): any {
+  try {
+    return this.utils.stringToJSON(jsonString);
+  } catch (error) {
+    console.warn('Invalid JSON:', jsonString, error);
+    return fallback;
+  }
+}
+
+// ❌ Avoid - Unsafe parsing
+const data = JSON.parse(jsonString); // Could throw
+```
+
+#### 2. Type Checking Edge Cases
+```typescript
+// ✅ Good - Handle edge cases
+isValidString(value: any): boolean {
+  return this.utils.isString(value) && value.trim().length > 0;
+}
+
+// ❌ Avoid - Incomplete validation
+const isString = this.utils.isString(value); // Could be empty string
+```
+
+#### 3. Expiration Calculation
+```typescript
+// ✅ Good - Handle invalid durations
+safeExpires(duration: string, fallback: number): number {
+  const expires = this.utils.expires(duration);
+  return expires || fallback;
+}
+
+// ❌ Avoid - No fallback
+const expires = this.utils.expires(duration); // Could be undefined
+```
+
+## Related Documentation
+
+- [Local Storage Service](local-storage/README.md)
+- [HTTP State Service](http-state/README.md)
+- [Database Manager Service](database/README.md)
+- [Architecture Overview](../architecture/README.md)