http-request-manager 18.7.20 → 18.7.21

package/UTILS_README.md

@@ -0,0 +1,1186 @@
+# Utils Service
+
+The `UtilsService` provides a collection of utility functions for common tasks including JSON handling, type checking, expiration management, conversions, and validation. These utilities simplify everyday development tasks.
+
+## Overview
+
+This service provides:
+
+- **JSON Handling** - Safe JSON parsing and stringification
+- **Type Checking** - Runtime type validation and verification
+- **Expiration Management** - Convert duration strings to epoch timestamps and check expiry
+- **Conversions** - Base32, binary, and other data format conversions
+- **Object Operations** - Deep comparison and property access
+- **Time Utilities** - Date/time calculations and formatting
+
+## Installation
+
+```typescript
+import { HttpRequestManagerModule } from 'http-request-manager';
+
+@NgModule({
+  imports: [HttpRequestManagerModule.forRoot({})]
+})
+export class AppModule { }
+```
+
+## Basic Usage
+
+### Service Injection
+
+```typescript
+import { Component, inject } from '@angular/core';
+import { UtilsService } from 'http-request-manager';
+
+@Component({
+  selector: 'app-utils-demo',
+  template: `
+    <div class="utils-demo">
+      <h2>Utils Service Demo</h2>
+      
+      <div class="json-section">
+        <h3>JSON Operations</h3>
+        <button (click)="testJsonOperations()">Test JSON Operations</button>
+        <div *ngIf="jsonResult">
+          <p>Original: {{ jsonResult.original }}</p>
+          <p>Parsed: {{ jsonResult.parsed | json }}</p>
+          <p>Stringified: {{ jsonResult.stringified }}</p>
+        </div>
+      </div>
+      
+      <div class="type-section">
+        <h3>Type Checking</h3>
+        <input [(ngModel)]="testValue" placeholder="Enter a value">
+        <button (click)="checkTypes()">Check Types</button>
+        <div *ngIf="typeResult">
+          <p>Is String: {{ typeResult.isString }}</p>
+          <p>Is Object: {{ typeResult.isObject }}</p>
+          <p>Is JSON: {{ typeResult.isJson }}</p>
+        </div>
+      </div>
+      
+      <div class="expiry-section">
+        <h3>Expiration Management</h3>
+        <button (click)="testExpiration()">Test Expiration</button>
+        <div *ngIf="expiryResult">
+          <p>1 day from now: {{ expiryResult.oneDay | date:'medium' }}</p>
+          <p>Current time: {{ expiryResult.current | date:'medium' }}</p>
+          <p>Has 1 day expired: {{ expiryResult.hasExpired }}</p>
+          <p>Time remaining: {{ expiryResult.timeRemaining }}</p>
+        </div>
+      </div>
+      
+      <div class="conversion-section">
+        <h3>Conversions</h3>
+        <button (click)="testConversions()">Test Conversions</button>
+        <div *ngIf="conversionResult">
+          <p>Base32 to Hex: {{ conversionResult.base32ToHex }}</p>
+          <p>Binary to Hex: {{ conversionResult.binaryToHex }}</p>
+        </div>
+      </div>
+    </div>
+  `
+})
+export class UtilsDemoComponent {
+  private utils = inject(UtilsService);
+  
+  testValue = '';
+  jsonResult: any;
+  typeResult: any;
+  expiryResult: any;
+  conversionResult: any;
+
+  testJsonOperations() {
+    const testObj = { name: 'John', age: 30, active: true };
+    
+    this.jsonResult = {
+      original: testObj,
+      parsed: this.utils.stringToJSON(JSON.stringify(testObj)),
+      stringified: this.utils.JSONToString(testObj)
+    };
+  }
+
+  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)