gthinking 1.2.1 → 2.1.1

package/src/utils/cache.ts

@@ -0,0 +1,363 @@
+/**
+ * Cache Utility for gthinking v2.0.0
+ * In-memory caching with TTL support
+ */
+
+import { CacheError } from '../types';
+import { Logger } from './logger';
+
+const logger = new Logger('Cache');
+
+/**
+ * Cache entry interface
+ */
+interface CacheEntry<T> {
+  value: T;
+  timestamp: number;
+  ttl: number;
+  accessCount: number;
+}
+
+/**
+ * Cache statistics interface
+ */
+export interface CacheStats {
+  size: number;
+  hits: number;
+  misses: number;
+  hitRate: number;
+  evictions: number;
+  totalAccesses: number;
+}
+
+/**
+ * Cache configuration interface
+ */
+export interface CacheConfig {
+  maxSize: number;
+  defaultTTL: number;
+  checkInterval: number;
+}
+
+/**
+ * Default cache configuration
+ */
+const defaultConfig: CacheConfig = {
+  maxSize: 1000,
+  defaultTTL: 3600000, // 1 hour
+  checkInterval: 60000, // 1 minute
+};
+
+/**
+ * In-memory cache with TTL support
+ */
+export class Cache<T> {
+  private cache: Map<string, CacheEntry<T>> = new Map();
+  private config: CacheConfig;
+  private stats = {
+    hits: 0,
+    misses: 0,
+    evictions: 0,
+    totalAccesses: 0,
+  };
+  private cleanupInterval: NodeJS.Timeout | null = null;
+
+  constructor(config: Partial<CacheConfig> = {}) {
+    this.config = { ...defaultConfig, ...config };
+    this.startCleanupInterval();
+  }
+
+  /**
+   * Get a value from the cache
+   * @param key - The cache key
+   * @returns The cached value or undefined
+   */
+  public get(key: string): T | undefined {
+    this.stats.totalAccesses++;
+    
+    const entry = this.cache.get(key);
+    
+    if (!entry) {
+      this.stats.misses++;
+      return undefined;
+    }
+    
+    // Check if entry has expired
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      this.stats.misses++;
+      return undefined;
+    }
+    
+    // Update access count
+    entry.accessCount++;
+    this.stats.hits++;
+    
+    return entry.value;
+  }
+
+  /**
+   * Set a value in the cache
+   * @param key - The cache key
+   * @param value - The value to cache
+   * @param ttl - Time to live in milliseconds (optional)
+   */
+  public set(key: string, value: T, ttl?: number): void {
+    // Evict entries if cache is full
+    if (this.cache.size >= this.config.maxSize && !this.cache.has(key)) {
+      this.evictLRU();
+    }
+    
+    const entry: CacheEntry<T> = {
+      value,
+      timestamp: Date.now(),
+      ttl: ttl ?? this.config.defaultTTL,
+      accessCount: 0,
+    };
+    
+    this.cache.set(key, entry);
+  }
+
+  /**
+   * Check if a key exists in the cache
+   * @param key - The cache key
+   * @returns True if the key exists and hasn't expired
+   */
+  public has(key: string): boolean {
+    const entry = this.cache.get(key);
+    
+    if (!entry) {
+      return false;
+    }
+    
+    if (this.isExpired(entry)) {
+      this.cache.delete(key);
+      return false;
+    }
+    
+    return true;
+  }
+
+  /**
+   * Delete a key from the cache
+   * @param key - The cache key
+   * @returns True if the key was deleted
+   */
+  public delete(key: string): boolean {
+    return this.cache.delete(key);
+  }
+
+  /**
+   * Clear all entries from the cache
+   */
+  public clear(): void {
+    this.cache.clear();
+    logger.info('Cache cleared');
+  }
+
+  /**
+   * Get cache statistics
+   * @returns Cache statistics
+   */
+  public getStats(): CacheStats {
+    const totalAccesses = this.stats.totalAccesses;
+    const hitRate = totalAccesses > 0 ? this.stats.hits / totalAccesses : 0;
+    
+    return {
+      size: this.cache.size,
+      hits: this.stats.hits,
+      misses: this.stats.misses,
+      hitRate,
+      evictions: this.stats.evictions,
+      totalAccesses,
+    };
+  }
+
+  /**
+   * Reset cache statistics
+   */
+  public resetStats(): void {
+    this.stats = {
+      hits: 0,
+      misses: 0,
+      evictions: 0,
+      totalAccesses: 0,
+    };
+  }
+
+  /**
+   * Get all keys in the cache
+   * @returns Array of cache keys
+   */
+  public keys(): string[] {
+    return Array.from(this.cache.keys());
+  }
+
+  /**
+   * Get the number of entries in the cache
+   * @returns Number of entries
+   */
+  public size(): number {
+    return this.cache.size;
+  }
+
+  /**
+   * Dispose of the cache and stop cleanup interval
+   */
+  public dispose(): void {
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.clear();
+  }
+
+  /**
+   * Check if an entry has expired
+   * @param entry - The cache entry
+   * @returns True if the entry has expired
+   */
+  private isExpired(entry: CacheEntry<T>): boolean {
+    return Date.now() - entry.timestamp > entry.ttl;
+  }
+
+  /**
+   * Evict the least recently used entry
+   */
+  private evictLRU(): void {
+    let oldestKey: string | null = null;
+    let oldestTimestamp = Infinity;
+    
+    for (const [key, entry] of this.cache.entries()) {
+      if (entry.timestamp < oldestTimestamp) {
+        oldestTimestamp = entry.timestamp;
+        oldestKey = key;
+      }
+    }
+    
+    if (oldestKey) {
+      this.cache.delete(oldestKey);
+      this.stats.evictions++;
+      logger.debug(`Evicted LRU entry: ${oldestKey}`);
+    }
+  }
+
+  /**
+   * Clean up expired entries
+   */
+  private cleanup(): void {
+    const now = Date.now();
+    let expiredCount = 0;
+    
+    for (const [key, entry] of this.cache.entries()) {
+      if (now - entry.timestamp > entry.ttl) {
+        this.cache.delete(key);
+        expiredCount++;
+      }
+    }
+    
+    if (expiredCount > 0) {
+      logger.debug(`Cleaned up ${expiredCount} expired entries`);
+    }
+  }
+
+  /**
+   * Start the cleanup interval
+   */
+  private startCleanupInterval(): void {
+    this.cleanupInterval = setInterval(() => {
+      this.cleanup();
+    }, this.config.checkInterval);
+  }
+}
+
+/**
+ * Cache manager for managing multiple cache instances
+ */
+export class CacheManager {
+  private caches: Map<string, Cache<unknown>> = new Map();
+
+  /**
+   * Get or create a cache instance
+   * @param name - The cache name
+   * @param config - Cache configuration
+   * @returns Cache instance
+   */
+  public getCache<T>(name: string, config?: Partial<CacheConfig>): Cache<T> {
+    if (!this.caches.has(name)) {
+      this.caches.set(name, new Cache<T>(config));
+    }
+    return this.caches.get(name) as Cache<T>;
+  }
+
+  /**
+   * Delete a cache instance
+   * @param name - The cache name
+   */
+  public deleteCache(name: string): void {
+    const cache = this.caches.get(name);
+    if (cache) {
+      cache.dispose();
+      this.caches.delete(name);
+    }
+  }
+
+  /**
+   * Clear all caches
+   */
+  public clearAll(): void {
+    for (const cache of this.caches.values()) {
+      cache.clear();
+    }
+  }
+
+  /**
+   * Dispose of all caches
+   */
+  public dispose(): void {
+    for (const [name, cache] of this.caches.entries()) {
+      cache.dispose();
+    }
+    this.caches.clear();
+  }
+
+  /**
+   * Get all cache names
+   * @returns Array of cache names
+   */
+  public getCacheNames(): string[] {
+    return Array.from(this.caches.keys());
+  }
+}
+
+// Export a singleton cache manager
+export const cacheManager = new CacheManager();
+
+/**
+ * Memoize decorator for caching function results
+ * @param fn - The function to memoize
+ * @param keyGenerator - Function to generate cache key from arguments
+ * @param ttl - Time to live in milliseconds
+ * @returns Memoized function
+ */
+export function memoize<T extends (...args: unknown[]) => unknown>(
+  fn: T,
+  keyGenerator?: (...args: Parameters<T>) => string,
+  ttl?: number
+): T {
+  const cache = new Cache<ReturnType<T>>();
+  
+  return function (...args: Parameters<T>): ReturnType<T> {
+    const key = keyGenerator ? keyGenerator(...args) : JSON.stringify(args);
+    
+    const cached = cache.get(key);
+    if (cached !== undefined) {
+      return cached;
+    }
+    
+    const result = fn(...args) as ReturnType<T>;
+    cache.set(key, result, ttl);
+    
+    return result;
+  } as T;
+}

package/src/utils/id-generator.ts

@@ -0,0 +1,135 @@
+/**
+ * ID Generator Utility for gthinking v2.0.0
+ * Secure and collision-resistant ID generation
+ */
+
+import { v4 as uuidv4, v5 as uuidv5 } from 'uuid';
+
+/**
+ * Generate a random UUID v4
+ * @returns A random UUID string
+ */
+export function generateUUID(): string {
+  return uuidv4();
+}
+
+/**
+ * Generate a deterministic UUID v5 based on a namespace and name
+ * @param namespace - The namespace UUID
+ * @param name - The name to hash
+ * @returns A deterministic UUID string
+ */
+export function generateDeterministicUUID(namespace: string, name: string): string {
+  return uuidv5(name, namespace);
+}
+
+/**
+ * Generate a short ID (8 characters) for internal use
+ * Note: This is not cryptographically secure, use only for non-sensitive IDs
+ * @returns A short random string
+ */
+export function generateShortId(): string {
+  return Math.random().toString(36).substring(2, 10);
+}
+
+/**
+ * Generate a timestamp-based ID with random suffix
+ * @param prefix - Optional prefix for the ID
+ * @returns A timestamp-based ID string
+ */
+export function generateTimestampId(prefix?: string): string {
+  const timestamp = Date.now().toString(36);
+  const random = Math.random().toString(36).substring(2, 6);
+  const id = `${timestamp}_${random}`;
+  return prefix ? `${prefix}_${id}` : id;
+}
+
+/**
+ * Generate a sequential ID with padding
+ * @param sequence - The sequence number
+ * @param padding - The number of digits to pad to
+ * @returns A padded sequential ID string
+ */
+export function generateSequentialId(sequence: number, padding = 6): string {
+  return sequence.toString().padStart(padding, '0');
+}
+
+/**
+ * Generate a compound ID from multiple parts
+ * @param parts - The parts to combine
+ * @param separator - The separator to use (default: '_')
+ * @returns A compound ID string
+ */
+export function generateCompoundId(parts: string[], separator = '_'): string {
+  return parts.join(separator);
+}
+
+/**
+ * Validate if a string is a valid UUID
+ * @param id - The string to validate
+ * @returns True if the string is a valid UUID
+ */
+export function isValidUUID(id: string): boolean {
+  const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return uuidRegex.test(id);
+}
+
+/**
+ * Namespace UUIDs for deterministic ID generation
+ */
+export const Namespaces = {
+  DNS: '6ba7b810-9dad-11d1-80b4-00c04fd430c8',
+  URL: '6ba7b811-9dad-11d1-80b4-00c04fd430c8',
+  OID: '6ba7b812-9dad-11d1-80b4-00c04fd430c8',
+  X500: '6ba7b814-9dad-11d1-80b4-00c04fd430c8',
+  // Custom namespaces for gthinking
+  SESSION: 'a7b8c9d0-e1f2-4a3b-8c4d-5e6f7a8b9c0d',
+  TASK: 'b8c9d0e1-f2a3-5b4c-9d5e-6f7a8b9c0d1e',
+  IDEA: 'c9d0e1f2-a3b4-6c5d-0e6f-7a8b9c0d1e2f',
+} as const;
+
+/**
+ * ID Generator class for managing ID generation with prefixes
+ */
+export class IdGenerator {
+  private counters: Map<string, number> = new Map();
+
+  /**
+   * Generate a prefixed ID with an auto-incrementing counter
+   * @param prefix - The prefix for the ID
+   * @returns A prefixed ID string
+   */
+  public generatePrefixedId(prefix: string): string {
+    const current = this.counters.get(prefix) || 0;
+    const next = current + 1;
+    this.counters.set(prefix, next);
+    return `${prefix}_${generateSequentialId(next)}`;
+  }
+
+  /**
+   * Reset the counter for a specific prefix
+   * @param prefix - The prefix to reset
+   */
+  public resetCounter(prefix: string): void {
+    this.counters.delete(prefix);
+  }
+
+  /**
+   * Reset all counters
+   */
+  public resetAllCounters(): void {
+    this.counters.clear();
+  }
+
+  /**
+   * Get the current counter value for a prefix
+   * @param prefix - The prefix to check
+   * @returns The current counter value
+   */
+  public getCounter(prefix: string): number {
+    return this.counters.get(prefix) || 0;
+  }
+}
+
+// Export a singleton instance
+export const idGenerator = new IdGenerator();

package/src/utils/index.ts

@@ -0,0 +1,22 @@
+/**
+ * Utils Index for gthinking v2.0.0
+ * Central export point for all utilities
+ */
+
+// ID Generator
+export * from './id-generator';
+
+// Validation
+export * from './validation';
+
+// Logger
+export * from './logger';
+
+// Cache
+export * from './cache';
+
+// Metrics
+export * from './metrics';
+
+// Timer
+export * from './timer';