@lgriffin/esi.ts 1.0.0 → 2.0.0

package/src/core/cache/ETagCacheManager.ts

@@ -0,0 +1,248 @@
+import { logInfo, logDebug, logWarn } from '../logger/loggerUtil';
+
+export interface CacheEntry {
+    etag: string;
+    data: any;
+    headers: Record<string, string>;
+    timestamp: number;
+    ttl?: number; // Time to live in milliseconds
+}
+
+export interface ETagCacheConfig {
+    maxEntries?: number;
+    defaultTtl?: number; // Default TTL in milliseconds
+    cleanupInterval?: number; // Cleanup interval in milliseconds
+    persistToStorage?: boolean;
+    storageKey?: string;
+}
+
+export class ETagCacheManager {
+    private cache: Map<string, CacheEntry> = new Map();
+    private config: Required<ETagCacheConfig>;
+    private cleanupTimer?: NodeJS.Timeout;
+
+    constructor(config: ETagCacheConfig = {}) {
+        this.config = {
+            maxEntries: config.maxEntries ?? 1000,
+            defaultTtl: config.defaultTtl ?? 5 * 60 * 1000, // 5 minutes default
+            cleanupInterval: config.cleanupInterval ?? 60 * 1000, // 1 minute cleanup
+            persistToStorage: config.persistToStorage ?? false,
+            storageKey: config.storageKey ?? 'esi-etag-cache'
+        };
+
+        if (this.config.persistToStorage) {
+            this.loadFromStorage();
+        }
+
+        this.startCleanupTimer();
+        logInfo(`ETag cache manager initialized with ${this.config.maxEntries} max entries`);
+    }
+
+    /**
+     * Get cached data if ETag matches
+     */
+    get(url: string): CacheEntry | null {
+        const entry = this.cache.get(url);
+        
+        if (!entry) {
+            return null;
+        }
+
+        // Check if entry has expired
+        if (this.isExpired(entry)) {
+            this.cache.delete(url);
+            logDebug(`Cache entry expired for ${url}`);
+            return null;
+        }
+
+        logDebug(`Cache hit for ${url} with ETag ${entry.etag}`);
+        return entry;
+    }
+
+    /**
+     * Get ETag for a URL (for If-None-Match header)
+     */
+    getETag(url: string): string | null {
+        const entry = this.get(url);
+        return entry ? entry.etag : null;
+    }
+
+    /**
+     * Set cache entry
+     */
+    set(url: string, etag: string, data: any, headers: Record<string, string>, customTtl?: number): void {
+        // Remove oldest entries if cache is full
+        if (this.cache.size >= this.config.maxEntries) {
+            this.evictOldest();
+        }
+
+        const entry: CacheEntry = {
+            etag,
+            data,
+            headers,
+            timestamp: Date.now(),
+            ttl: customTtl ?? this.config.defaultTtl
+        };
+
+        this.cache.set(url, entry);
+        logDebug(`Cached response for ${url} with ETag ${etag}`);
+
+        if (this.config.persistToStorage) {
+            this.saveToStorage();
+        }
+    }
+
+    /**
+     * Check if cached data exists and is valid
+     */
+    has(url: string): boolean {
+        const entry = this.cache.get(url);
+        return entry !== undefined && !this.isExpired(entry);
+    }
+
+    /**
+     * Clear specific cache entry
+     */
+    delete(url: string): boolean {
+        const deleted = this.cache.delete(url);
+        if (deleted && this.config.persistToStorage) {
+            this.saveToStorage();
+        }
+        return deleted;
+    }
+
+    /**
+     * Clear all cache entries
+     */
+    clear(): void {
+        this.cache.clear();
+        if (this.config.persistToStorage) {
+            this.saveToStorage();
+        }
+        logInfo('ETag cache cleared');
+    }
+
+    /**
+     * Get cache statistics
+     */
+    getStats(): {
+        totalEntries: number;
+        maxEntries: number;
+        hitRate: number;
+        oldestEntry: number | null;
+        newestEntry: number | null;
+    } {
+        const entries = Array.from(this.cache.values());
+        const timestamps = entries.map(e => e.timestamp);
+        
+        return {
+            totalEntries: this.cache.size,
+            maxEntries: this.config.maxEntries,
+            hitRate: 0, // Would need to track hits/misses for this
+            oldestEntry: timestamps.length > 0 ? Math.min(...timestamps) : null,
+            newestEntry: timestamps.length > 0 ? Math.max(...timestamps) : null
+        };
+    }
+
+    /**
+     * Update cache configuration
+     */
+    updateConfig(newConfig: Partial<ETagCacheConfig>): void {
+        this.config = { ...this.config, ...newConfig };
+        logInfo('ETag cache configuration updated');
+    }
+
+    /**
+     * Cleanup expired entries
+     */
+    cleanup(): number {
+        const beforeSize = this.cache.size;
+        const now = Date.now();
+        const expiredKeys: string[] = [];
+
+        for (const [url, entry] of this.cache.entries()) {
+            if (this.isExpired(entry)) {
+                expiredKeys.push(url);
+            }
+        }
+
+        expiredKeys.forEach(key => this.cache.delete(key));
+
+        const cleanedCount = beforeSize - this.cache.size;
+        if (cleanedCount > 0) {
+            logDebug(`Cleaned up ${cleanedCount} expired cache entries`);
+            if (this.config.persistToStorage) {
+                this.saveToStorage();
+            }
+        }
+
+        return cleanedCount;
+    }
+
+    /**
+     * Shutdown cache manager
+     */
+    shutdown(): void {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+        }
+        if (this.config.persistToStorage) {
+            this.saveToStorage();
+        }
+        logInfo('ETag cache manager shut down');
+    }
+
+    private isExpired(entry: CacheEntry): boolean {
+        if (!entry.ttl) return false;
+        return Date.now() - entry.timestamp > entry.ttl;
+    }
+
+    private evictOldest(): void {
+        let oldestKey: string | null = null;
+        let oldestTime = Infinity;
+
+        for (const [key, entry] of this.cache.entries()) {
+            if (entry.timestamp < oldestTime) {
+                oldestTime = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+
+        if (oldestKey) {
+            this.cache.delete(oldestKey);
+            logDebug(`Evicted oldest cache entry: ${oldestKey}`);
+        }
+    }
+
+    private startCleanupTimer(): void {
+        this.cleanupTimer = setInterval(() => {
+            this.cleanup();
+        }, this.config.cleanupInterval);
+    }
+
+    private loadFromStorage(): void {
+        try {
+            if (typeof localStorage !== 'undefined') {
+                const stored = localStorage.getItem(this.config.storageKey);
+                if (stored) {
+                    const data = JSON.parse(stored);
+                    this.cache = new Map(data);
+                    logInfo(`Loaded ${this.cache.size} entries from storage`);
+                }
+            }
+        } catch (error) {
+            logWarn(`Failed to load cache from storage: ${error}`);
+        }
+    }
+
+    private saveToStorage(): void {
+        try {
+            if (typeof localStorage !== 'undefined') {
+                const data = Array.from(this.cache.entries());
+                localStorage.setItem(this.config.storageKey, JSON.stringify(data));
+            }
+        } catch (error) {
+            logWarn(`Failed to save cache to storage: ${error}`);
+        }
+    }
+}

package/src/core/container/Container.ts

@@ -0,0 +1,176 @@
+export type Factory<T = any> = () => T;
+export type AsyncFactory<T = any> = () => Promise<T>;
+
+export interface ContainerConfig {
+    enableLogging?: boolean;
+    enableCircularDependencyDetection?: boolean;
+}
+
+export class CircularDependencyError extends Error {
+    constructor(dependencyChain: string[]) {
+        super(`Circular dependency detected: ${dependencyChain.join(' -> ')}`);
+        this.name = 'CircularDependencyError';
+    }
+}
+
+export class Container {
+    private dependencies = new Map<string, Factory>();
+    private singletons = new Map<string, any>();
+    private resolutionStack: string[] = [];
+    private config: ContainerConfig;
+
+    constructor(config: ContainerConfig = {}) {
+        this.config = {
+            enableLogging: false,
+            enableCircularDependencyDetection: true,
+            ...config
+        };
+    }
+
+    /**
+     * Register a factory function for a dependency
+     */
+    register<T>(token: string, factory: Factory<T>, singleton: boolean = false): this {
+        if (this.config.enableLogging) {
+            console.log(`Registering dependency: ${token} (singleton: ${singleton})`);
+        }
+
+        this.dependencies.set(token, factory);
+        
+        if (singleton) {
+            // Pre-resolve singleton to catch errors early
+            this.resolve<T>(token);
+        }
+
+        return this;
+    }
+
+    /**
+     * Register a singleton dependency
+     */
+    registerSingleton<T>(token: string, factory: Factory<T>): this {
+        return this.register(token, factory, true);
+    }
+
+    /**
+     * Register an instance directly as a singleton
+     */
+    registerInstance<T>(token: string, instance: T): this {
+        this.singletons.set(token, instance);
+        return this;
+    }
+
+    /**
+     * Resolve a dependency by token
+     */
+    resolve<T>(token: string): T {
+        // Check if it's already a singleton instance
+        if (this.singletons.has(token)) {
+            return this.singletons.get(token) as T;
+        }
+
+        // Get the factory
+        const factory = this.dependencies.get(token);
+        if (!factory) {
+            throw new Error(`Dependency '${token}' not found. Available dependencies: ${Array.from(this.dependencies.keys()).join(', ')}`);
+        }
+
+        // Check for circular dependencies
+        if (this.config.enableCircularDependencyDetection && this.resolutionStack.includes(token)) {
+            throw new CircularDependencyError([...this.resolutionStack, token]);
+        }
+
+        // Add to resolution stack
+        this.resolutionStack.push(token);
+
+        try {
+            const instance = factory();
+
+            // Store as singleton if it was registered as one
+            if (this.isSingleton(token)) {
+                this.singletons.set(token, instance);
+            }
+
+            return instance as T;
+        } finally {
+            // Remove from resolution stack
+            this.resolutionStack.pop();
+        }
+    }
+
+    /**
+     * Check if a dependency is registered
+     */
+    has(token: string): boolean {
+        return this.dependencies.has(token) || this.singletons.has(token);
+    }
+
+    /**
+     * Remove a dependency
+     */
+    remove(token: string): boolean {
+        const hadDependency = this.dependencies.delete(token);
+        const hadSingleton = this.singletons.delete(token);
+        return hadDependency || hadSingleton;
+    }
+
+    /**
+     * Clear all dependencies
+     */
+    clear(): void {
+        this.dependencies.clear();
+        this.singletons.clear();
+        this.resolutionStack = [];
+    }
+
+    /**
+     * Get all registered dependency tokens
+     */
+    getRegisteredTokens(): string[] {
+        const dependencyTokens = Array.from(this.dependencies.keys());
+        const singletonTokens = Array.from(this.singletons.keys());
+        return [...new Set([...dependencyTokens, ...singletonTokens])];
+    }
+
+    /**
+     * Create a child container that inherits from this one
+     */
+    createChild(): Container {
+        const child = new Container(this.config);
+        
+        // Copy dependencies (not instances)
+        for (const [token, factory] of this.dependencies) {
+            child.dependencies.set(token, factory);
+        }
+
+        return child;
+    }
+
+    private isSingleton(token: string): boolean {
+        // Check if the token was registered with singleton behavior
+        // This is determined by checking if resolve was called during registration
+        return false; // For now, we'll manage this manually
+    }
+}
+
+// Global container instance
+export const container = new Container({
+    enableLogging: process.env.NODE_ENV === 'development',
+    enableCircularDependencyDetection: true
+});
+
+// Dependency injection decorators (if using experimental decorators)
+export function Injectable(token?: string) {
+    return function <T extends new (...args: any[]) => {}>(constructor: T) {
+        const dependencyToken = token || constructor.name;
+        container.register(dependencyToken, () => new constructor());
+        return constructor;
+    };
+}
+
+export function Inject(token: string) {
+    return function (target: any, propertyKey: string | symbol | undefined, parameterIndex: number) {
+        // This would require reflect-metadata for full implementation
+        // For now, it's a placeholder for future enhancement
+    };
+}

package/src/core/errors/ApiError.ts

@@ -0,0 +1,153 @@
+export enum ApiErrorType {
+    NETWORK_ERROR = 'NETWORK_ERROR',
+    AUTHENTICATION_ERROR = 'AUTHENTICATION_ERROR',
+    AUTHORIZATION_ERROR = 'AUTHORIZATION_ERROR',
+    RATE_LIMIT_ERROR = 'RATE_LIMIT_ERROR',
+    SERVER_ERROR = 'SERVER_ERROR',
+    CLIENT_ERROR = 'CLIENT_ERROR',
+    VALIDATION_ERROR = 'VALIDATION_ERROR',
+    NOT_FOUND_ERROR = 'NOT_FOUND_ERROR',
+    TIMEOUT_ERROR = 'TIMEOUT_ERROR',
+    UNKNOWN_ERROR = 'UNKNOWN_ERROR'
+}
+
+export class ApiError extends Error {
+    public readonly type: ApiErrorType;
+    public readonly statusCode?: number;
+    public readonly details?: any;
+    public readonly timestamp: Date;
+    public readonly requestId?: string;
+
+    constructor(
+        message: string,
+        type: ApiErrorType = ApiErrorType.UNKNOWN_ERROR,
+        statusCode?: number,
+        details?: any,
+        requestId?: string
+    ) {
+        super(message);
+        this.name = 'ApiError';
+        this.type = type;
+        this.statusCode = statusCode;
+        this.details = details;
+        this.timestamp = new Date();
+        this.requestId = requestId;
+
+        // Maintains proper stack trace for where our error was thrown (only available on V8)
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ApiError);
+        }
+    }
+
+    static fromHttpStatus(statusCode: number, message: string, details?: any, requestId?: string): ApiError {
+        let type: ApiErrorType;
+
+        switch (Math.floor(statusCode / 100)) {
+            case 4:
+                if (statusCode === 401) {
+                    type = ApiErrorType.AUTHENTICATION_ERROR;
+                } else if (statusCode === 403) {
+                    type = ApiErrorType.AUTHORIZATION_ERROR;
+                } else if (statusCode === 404) {
+                    type = ApiErrorType.NOT_FOUND_ERROR;
+                } else if (statusCode === 429) {
+                    type = ApiErrorType.RATE_LIMIT_ERROR;
+                } else {
+                    type = ApiErrorType.CLIENT_ERROR;
+                }
+                break;
+            case 5:
+                type = ApiErrorType.SERVER_ERROR;
+                break;
+            default:
+                type = ApiErrorType.UNKNOWN_ERROR;
+        }
+
+        return new ApiError(message, type, statusCode, details, requestId);
+    }
+
+    static networkError(message: string = 'Network connection failed', details?: any): ApiError {
+        return new ApiError(message, ApiErrorType.NETWORK_ERROR, undefined, details);
+    }
+
+    static timeoutError(message: string = 'Request timeout', details?: any): ApiError {
+        return new ApiError(message, ApiErrorType.TIMEOUT_ERROR, undefined, details);
+    }
+
+    static validationError(message: string, details?: any): ApiError {
+        return new ApiError(message, ApiErrorType.VALIDATION_ERROR, 400, details);
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            type: this.type,
+            statusCode: this.statusCode,
+            details: this.details,
+            timestamp: this.timestamp.toISOString(),
+            requestId: this.requestId,
+            stack: this.stack
+        };
+    }
+}
+
+export class ErrorHandler {
+    static handle(error: any, requestId?: string): never {
+        if (error instanceof ApiError) {
+            throw error;
+        }
+
+        // Handle Axios/HTTP errors
+        if (error.response) {
+            const statusCode = error.response.status;
+            const message = error.response.data?.error || 
+                           error.response.data?.message || 
+                           error.message || 
+                           `HTTP ${statusCode} Error`;
+            
+            throw ApiError.fromHttpStatus(statusCode, message, error.response.data, requestId);
+        }
+
+        // Handle network errors
+        if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND' || error.code === 'ECONNRESET') {
+            throw ApiError.networkError(`Network error: ${error.message}`, { code: error.code });
+        }
+
+        // Handle timeout errors
+        if (error.code === 'ECONNABORTED' || error.message?.includes('timeout')) {
+            throw ApiError.timeoutError(`Request timeout: ${error.message}`);
+        }
+
+        // Default to unknown error
+        throw new ApiError(
+            error.message || 'An unknown error occurred',
+            ApiErrorType.UNKNOWN_ERROR,
+            undefined,
+            error,
+            requestId
+        );
+    }
+
+    static isRetryable(error: ApiError): boolean {
+        return [
+            ApiErrorType.NETWORK_ERROR,
+            ApiErrorType.TIMEOUT_ERROR,
+            ApiErrorType.SERVER_ERROR,
+            ApiErrorType.RATE_LIMIT_ERROR
+        ].includes(error.type);
+    }
+
+    static getRetryDelay(error: ApiError, attempt: number): number {
+        if (error.type === ApiErrorType.RATE_LIMIT_ERROR) {
+            // Check for Retry-After header in details
+            const retryAfter = error.details?.headers?.['retry-after'];
+            if (retryAfter) {
+                return parseInt(retryAfter) * 1000; // Convert to milliseconds
+            }
+        }
+
+        // Exponential backoff: 1s, 2s, 4s, 8s, etc.
+        return Math.min(1000 * Math.pow(2, attempt - 1), 30000); // Max 30 seconds
+    }
+}