@json-to-office/shared 0.1.0

package/dist/cache/index.js

@@ -0,0 +1,738 @@
+// src/cache/manager.ts
+import { EventEmitter } from "events";
+var ComponentCacheManager = class extends EventEmitter {
+  config;
+  stats;
+  constructor(config) {
+    super();
+    this.config = config;
+    this.stats = this.initializeStats();
+  }
+  /**
+   * Get cache statistics with deep immutability
+   */
+  getStats() {
+    const componentStatsCopy = /* @__PURE__ */ new Map();
+    this.stats.componentStats.forEach((value, key) => {
+      componentStatsCopy.set(key, { ...value });
+    });
+    return {
+      ...this.stats,
+      componentStats: componentStatsCopy
+    };
+  }
+  /**
+   * Get configuration with deep immutability
+   */
+  getConfig() {
+    const configCopy = {
+      enabled: this.config.enabled,
+      evictionPolicy: this.config.evictionPolicy,
+      memory: { ...this.config.memory },
+      performance: { ...this.config.performance }
+    };
+    if (this.config.disk) {
+      configCopy.disk = { ...this.config.disk };
+    }
+    if (this.config.componentConfig) {
+      configCopy.componentConfig = {};
+      for (const [key, value] of Object.entries(this.config.componentConfig)) {
+        configCopy.componentConfig[key] = { ...value };
+      }
+    }
+    return configCopy;
+  }
+  /**
+   * Get multiple entries (batch operation)
+   */
+  async getMany(keys) {
+    const results = /* @__PURE__ */ new Map();
+    if (this.config.performance.parallelProcessing) {
+      const promises = keys.map(async (key) => {
+        const value = await this.get(key);
+        if (value) results.set(key, value);
+      });
+      await Promise.all(promises);
+    } else {
+      for (const key of keys) {
+        const value = await this.get(key);
+        if (value) results.set(key, value);
+      }
+    }
+    return results;
+  }
+  /**
+   * Set multiple entries (batch operation)
+   */
+  async setMany(entries) {
+    if (this.config.performance.parallelProcessing) {
+      const promises = entries.map(([key, value]) => this.set(key, value));
+      await Promise.all(promises);
+    } else {
+      for (const [key, value] of entries) {
+        await this.set(key, value);
+      }
+    }
+  }
+  /**
+   * Delete multiple entries
+   */
+  async deleteMany(keys) {
+    let deleted = 0;
+    if (this.config.performance.parallelProcessing) {
+      const results = await Promise.all(keys.map((key) => this.delete(key)));
+      deleted = results.filter(Boolean).length;
+    } else {
+      for (const key of keys) {
+        if (await this.delete(key)) {
+          deleted++;
+        }
+      }
+    }
+    return deleted;
+  }
+  /**
+   * Initialize statistics
+   */
+  initializeStats() {
+    return {
+      entries: 0,
+      totalSize: 0,
+      hitRate: 0,
+      missRate: 0,
+      totalHits: 0,
+      totalMisses: 0,
+      avgResponseTime: 0,
+      evictions: 0,
+      componentStats: /* @__PURE__ */ new Map()
+    };
+  }
+  /**
+   * Update statistics on cache hit
+   */
+  updateHitStats(key, component) {
+    this.stats.totalHits++;
+    this.updateComponentStats(component.componentName, "hit");
+    this.recalculateRates();
+    this.emit("hit", key, component);
+  }
+  /**
+   * Update statistics on cache miss
+   */
+  updateMissStats(key, componentName) {
+    this.stats.totalMisses++;
+    if (componentName) {
+      this.updateComponentStats(componentName, "miss");
+    }
+    this.recalculateRates();
+    this.emit("miss", key);
+  }
+  /**
+   * Update component-specific statistics
+   */
+  updateComponentStats(componentName, event) {
+    if (!this.stats.componentStats.has(componentName)) {
+      this.stats.componentStats.set(componentName, {
+        name: componentName,
+        hits: 0,
+        misses: 0,
+        avgProcessTime: 0,
+        avgSize: 0,
+        entries: 0
+      });
+    }
+    const stats = this.stats.componentStats.get(componentName);
+    if (event === "hit") {
+      stats.hits++;
+    } else {
+      stats.misses++;
+    }
+  }
+  /**
+   * Recalculate hit/miss rates
+   */
+  recalculateRates() {
+    const total = this.stats.totalHits + this.stats.totalMisses;
+    if (total > 0) {
+      this.stats.hitRate = this.stats.totalHits / total;
+      this.stats.missRate = this.stats.totalMisses / total;
+    }
+  }
+  /**
+   * Emit statistics periodically
+   */
+  emitStats() {
+    this.emit("stats", this.getStats());
+  }
+};
+
+// src/cache/memory-cache.ts
+var LRUNode = class {
+  key;
+  value;
+  prev = null;
+  next = null;
+  constructor(key, value) {
+    this.key = key;
+    this.value = value;
+  }
+};
+var MemoryCache = class extends ComponentCacheManager {
+  cache;
+  head = null;
+  tail = null;
+  currentSize = 0;
+  keyToComponentName = /* @__PURE__ */ new Map();
+  cleanupTimer;
+  constructor(config) {
+    super(config);
+    this.cache = /* @__PURE__ */ new Map();
+    if (config.memory.cleanupInterval > 0) {
+      this.startCleanupTimer();
+    }
+  }
+  async get(key) {
+    const node = this.cache.get(key);
+    if (!node) {
+      const componentName = this.keyToComponentName.get(key) || this.extractComponentNameFromKey(key);
+      this.updateMissStats(key, componentName);
+      return void 0;
+    }
+    const component = node.value;
+    if (this.isExpired(component)) {
+      await this.delete(key);
+      this.updateMissStats(key, component.componentName);
+      return void 0;
+    }
+    component.lastAccessed = Date.now();
+    component.hits++;
+    this.moveToHead(node);
+    this.updateHitStats(key, component);
+    return component;
+  }
+  async set(key, component) {
+    if (!this.isCacheable(component.componentName)) {
+      return;
+    }
+    this.keyToComponentName.set(key, component.componentName);
+    if (this.cache.has(key)) {
+      await this.delete(key);
+    }
+    await this.ensureSpace(component.size);
+    const node = new LRUNode(key, component);
+    this.cache.set(key, node);
+    this.addToHead(node);
+    this.currentSize += component.size;
+    this.stats.entries++;
+    this.stats.totalSize = this.currentSize;
+    let componentStats = this.stats.componentStats.get(component.componentName);
+    if (!componentStats) {
+      componentStats = {
+        name: component.componentName,
+        hits: 0,
+        misses: 0,
+        entries: 0,
+        avgSize: 0,
+        avgProcessTime: 0
+      };
+      this.stats.componentStats.set(component.componentName, componentStats);
+    }
+    componentStats.entries++;
+    componentStats.avgSize = (componentStats.avgSize * (componentStats.entries - 1) + component.size) / componentStats.entries;
+    this.emit("set", key, component);
+  }
+  async has(key) {
+    const node = this.cache.get(key);
+    if (!node) return false;
+    return !this.isExpired(node.value);
+  }
+  async delete(key) {
+    const node = this.cache.get(key);
+    if (!node) return false;
+    this.removeNode(node);
+    this.cache.delete(key);
+    this.keyToComponentName.delete(key);
+    this.currentSize -= node.value.size;
+    this.stats.entries--;
+    this.stats.totalSize = this.currentSize;
+    const componentStats = this.stats.componentStats.get(node.value.componentName);
+    if (componentStats && componentStats.entries > 0) {
+      componentStats.entries--;
+    }
+    return true;
+  }
+  async clear() {
+    this.cache.clear();
+    this.keyToComponentName.clear();
+    this.head = null;
+    this.tail = null;
+    this.currentSize = 0;
+    this.stats = this.initializeStats();
+  }
+  async getKeys() {
+    return Array.from(this.cache.keys());
+  }
+  /**
+   * Extract component name from cache key
+   */
+  extractComponentNameFromKey(key) {
+    const parts = key.split(":");
+    return parts.length >= 2 ? parts[1] : void 0;
+  }
+  /**
+   * Check if component is expired
+   */
+  isExpired(component) {
+    if (!component.ttl) return false;
+    return Date.now() - component.timestamp > component.ttl * 1e3;
+  }
+  /**
+   * Check if component is cacheable
+   */
+  isCacheable(componentName) {
+    const componentConfig = this.config.componentConfig?.[componentName];
+    return componentConfig?.cacheable !== false;
+  }
+  /**
+   * Ensure enough space for new entry
+   */
+  async ensureSpace(requiredSize) {
+    const maxSize = this.config.memory.maxSize * 1024 * 1024;
+    while (this.currentSize + requiredSize > maxSize && this.tail) {
+      const keyToEvict = this.tail.key;
+      await this.delete(keyToEvict);
+      this.stats.evictions++;
+      this.emit("evict", keyToEvict, "size");
+    }
+    const maxEntries = this.config.memory.maxEntries;
+    while (this.stats.entries >= maxEntries && this.tail) {
+      const keyToEvict = this.tail.key;
+      await this.delete(keyToEvict);
+      this.stats.evictions++;
+      this.emit("evict", keyToEvict, "size");
+    }
+  }
+  /**
+   * LRU operations - Add node to head
+   */
+  addToHead(node) {
+    node.prev = null;
+    node.next = this.head;
+    if (this.head) {
+      this.head.prev = node;
+    }
+    this.head = node;
+    if (!this.tail) {
+      this.tail = node;
+    }
+  }
+  /**
+   * Remove node from list
+   */
+  removeNode(node) {
+    if (node.prev) {
+      node.prev.next = node.next;
+    } else {
+      this.head = node.next;
+    }
+    if (node.next) {
+      node.next.prev = node.prev;
+    } else {
+      this.tail = node.prev;
+    }
+  }
+  /**
+   * Move node to head
+   */
+  moveToHead(node) {
+    if (node === this.head) return;
+    this.removeNode(node);
+    this.addToHead(node);
+  }
+  /**
+   * Start cleanup timer for expired entries
+   */
+  startCleanupTimer() {
+    this.cleanupTimer = setInterval(
+      async () => {
+        const keysToDelete = [];
+        for (const [key, node] of this.cache) {
+          if (this.isExpired(node.value)) {
+            keysToDelete.push(key);
+          }
+        }
+        for (const key of keysToDelete) {
+          await this.delete(key);
+          this.stats.evictions++;
+          this.emit("evict", key, "ttl");
+        }
+      },
+      (this.config.memory?.cleanupInterval || 300) * 1e3
+    );
+  }
+  /**
+   * Stop cleanup timer
+   */
+  destroy() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+    }
+  }
+};
+
+// src/cache/config.ts
+var DEFAULT_CACHE_CONFIG = {
+  enabled: true,
+  memory: {
+    enabled: true,
+    maxSize: 100,
+    // 100MB
+    maxEntries: 1e3,
+    defaultTTL: 3600,
+    // 1 hour
+    cleanupInterval: 300
+    // 5 minutes
+  },
+  evictionPolicy: "lru",
+  componentConfig: {
+    // Static content - longer TTL
+    text: { cacheable: true, ttl: 7200 },
+    // 2 hours
+    heading: { cacheable: true, ttl: 7200 },
+    columns: { cacheable: true, ttl: 3600 },
+    // 1 hour
+    section: { cacheable: true, ttl: 3600 },
+    // Dynamic content - shorter TTL
+    "custom-data": { cacheable: true, ttl: 300 },
+    // 5 minutes
+    "api-content": { cacheable: true, ttl: 180 },
+    // 3 minutes
+    // Resource-intensive components - medium TTL
+    image: { cacheable: true, ttl: 1800 },
+    // 30 minutes
+    table: { cacheable: true, ttl: 1800 }
+  },
+  performance: {
+    trackMetrics: true,
+    metricsSampleRate: 1,
+    enableWarming: false,
+    parallelProcessing: true
+  }
+};
+function getCacheConfigFromEnv() {
+  const config = {};
+  if (process.env.CACHE_ENABLED !== void 0) {
+    config.enabled = process.env.CACHE_ENABLED !== "false";
+  }
+  if (process.env.CACHE_MAX_SIZE || process.env.CACHE_MAX_ENTRIES || process.env.CACHE_TTL) {
+    config.memory = {
+      enabled: true,
+      maxSize: parseInt(process.env.CACHE_MAX_SIZE || "100"),
+      maxEntries: parseInt(process.env.CACHE_MAX_ENTRIES || "1000"),
+      defaultTTL: parseInt(process.env.CACHE_TTL || "3600"),
+      cleanupInterval: parseInt(process.env.CACHE_CLEANUP_INTERVAL || "300")
+    };
+  }
+  if (process.env.CACHE_TRACK_METRICS !== void 0 || process.env.CACHE_WARMING !== void 0) {
+    config.performance = {
+      trackMetrics: process.env.CACHE_TRACK_METRICS !== "false",
+      metricsSampleRate: parseFloat(process.env.CACHE_SAMPLE_RATE || "1.0"),
+      enableWarming: process.env.CACHE_WARMING === "true",
+      parallelProcessing: process.env.CACHE_PARALLEL !== "false"
+    };
+  }
+  return config;
+}
+function mergeConfigs(...configs) {
+  const merged = { ...DEFAULT_CACHE_CONFIG };
+  for (const config of configs) {
+    if (config.enabled !== void 0) {
+      merged.enabled = config.enabled;
+    }
+    if (config.memory) {
+      merged.memory = { ...merged.memory, ...config.memory };
+    }
+    if (config.disk) {
+      merged.disk = { ...merged.disk, ...config.disk };
+    }
+    if (config.evictionPolicy) {
+      merged.evictionPolicy = config.evictionPolicy;
+    }
+    if (config.componentConfig) {
+      merged.componentConfig = { ...merged.componentConfig, ...config.componentConfig };
+    }
+    if (config.performance) {
+      merged.performance = { ...merged.performance, ...config.performance };
+    }
+  }
+  return merged;
+}
+
+// src/cache/analytics.ts
+var ComponentCacheAnalytics = class {
+  historyWindow = 36e5;
+  // 1 hour in milliseconds
+  metricsHistory = /* @__PURE__ */ new Map();
+  performanceBaseline = /* @__PURE__ */ new Map();
+  /**
+   * Analyze cache statistics and generate comprehensive report
+   */
+  analyzeCache(stats) {
+    const componentMetrics = this.calculateComponentMetrics(stats);
+    const trends = this.calculateTrends(stats);
+    const recommendations = this.generateRecommendations(componentMetrics, trends);
+    const healthScore = this.calculateHealthScore(componentMetrics);
+    const overallEfficiency = this.calculateOverallEfficiency(componentMetrics);
+    const performanceGain = this.calculatePerformanceGain(componentMetrics);
+    const sortedByEfficiency = [...componentMetrics].sort(
+      (a, b) => b.efficiencyScore - a.efficiencyScore
+    );
+    const topPerformers = sortedByEfficiency.slice(0, 3).map((m) => m.componentName);
+    const needsAttention = sortedByEfficiency.filter((m) => m.efficiencyScore < 50).map((m) => m.componentName);
+    return {
+      timestamp: Date.now(),
+      healthScore,
+      overallEfficiency,
+      componentMetrics,
+      trends,
+      recommendations,
+      topPerformers,
+      needsAttention,
+      performanceGain
+    };
+  }
+  /**
+   * Calculate detailed metrics for each component
+   */
+  calculateComponentMetrics(stats) {
+    const metrics = [];
+    stats.componentStats.forEach((componentStats, componentName) => {
+      const totalRequests = componentStats.hits + componentStats.misses;
+      const hitRate = totalRequests > 0 ? componentStats.hits / totalRequests : 0;
+      const efficiencyScore = this.calculateEfficiencyScore(
+        hitRate,
+        componentStats.avgProcessTime,
+        componentStats.avgSize,
+        componentStats.entries
+      );
+      const timeSaved = componentStats.hits * componentStats.avgProcessTime;
+      const memoryCost = componentStats.entries * componentStats.avgSize;
+      const timeBenefit = timeSaved;
+      const costBenefitRatio = memoryCost > 0 ? timeBenefit / memoryCost : 0;
+      metrics.push({
+        componentName,
+        hitRate,
+        totalRequests,
+        avgHitTime: 1,
+        // Cache hits are typically ~1ms
+        avgMissTime: componentStats.avgProcessTime,
+        efficiencyScore,
+        memoryUsage: componentStats.entries * componentStats.avgSize,
+        timeSaved,
+        costBenefitRatio
+      });
+    });
+    return metrics;
+  }
+  /**
+   * Calculate efficiency score for a component
+   */
+  calculateEfficiencyScore(hitRate, avgProcessTime, avgSize, entries) {
+    const hitRateWeight = 0.4;
+    const processingTimeWeight = 0.3;
+    const memorySizeWeight = 0.2;
+    const utilizationWeight = 0.1;
+    const hitRateScore = hitRate * 100;
+    const processingTimeScore = Math.min(100, avgProcessTime / 10 * 100);
+    const memorySizeScore = Math.max(0, 100 - avgSize / 1e4 * 100);
+    const utilizationScore = Math.min(100, entries / 100 * 100);
+    const score = hitRateScore * hitRateWeight + processingTimeScore * processingTimeWeight + memorySizeScore * memorySizeWeight + utilizationScore * utilizationWeight;
+    return Math.round(score);
+  }
+  /**
+   * Calculate trends over time
+   */
+  calculateTrends(stats) {
+    const trends = [];
+    const now = Date.now();
+    stats.componentStats.forEach((componentStats, componentName) => {
+      const historyKey = `${componentName}_hitRate`;
+      if (!this.metricsHistory.has(historyKey)) {
+        this.metricsHistory.set(historyKey, []);
+      }
+      const history = this.metricsHistory.get(historyKey);
+      const totalRequests = componentStats.hits + componentStats.misses;
+      const hitRate = totalRequests > 0 ? componentStats.hits / totalRequests : 0;
+      history.push({ timestamp: now, value: hitRate });
+      const cutoff = now - this.historyWindow;
+      const cleanedHistory = history.filter(
+        (point) => point.timestamp > cutoff
+      );
+      this.metricsHistory.set(historyKey, cleanedHistory);
+      trends.push({
+        componentName,
+        hitRateTrend: [...cleanedHistory],
+        requestVolumeTrend: this.getOrCreateHistory(
+          `${componentName}_volume`,
+          totalRequests
+        ),
+        responseTimeTrend: this.getOrCreateHistory(
+          `${componentName}_response`,
+          componentStats.avgProcessTime
+        ),
+        memoryUsageTrend: this.getOrCreateHistory(
+          `${componentName}_memory`,
+          componentStats.entries * componentStats.avgSize
+        )
+      });
+    });
+    return trends;
+  }
+  /**
+   * Get or create history for a metric
+   */
+  getOrCreateHistory(key, currentValue) {
+    const now = Date.now();
+    if (!this.metricsHistory.has(key)) {
+      this.metricsHistory.set(key, []);
+    }
+    const history = this.metricsHistory.get(key);
+    history.push({ timestamp: now, value: currentValue });
+    const cutoff = now - this.historyWindow;
+    const cleanedHistory = history.filter((point) => point.timestamp > cutoff);
+    this.metricsHistory.set(key, cleanedHistory);
+    return [...cleanedHistory];
+  }
+  /**
+   * Generate optimization recommendations
+   */
+  generateRecommendations(metrics, trends) {
+    const recommendations = [];
+    metrics.forEach((metric) => {
+      const trend = trends.find((t) => t.componentName === metric.componentName);
+      if (metric.hitRate < 0.3 && metric.totalRequests > 10) {
+        recommendations.push({
+          componentName: metric.componentName,
+          type: "increase_ttl",
+          description: `Increase TTL for ${metric.componentName} components to improve hit rate`,
+          expectedImprovement: 20,
+          priority: 4,
+          reasoning: `Current hit rate of ${(metric.hitRate * 100).toFixed(1)}% is below optimal threshold. Increasing TTL could improve cache effectiveness.`
+        });
+      }
+      if (metric.memoryUsage > 1e6 && metric.hitRate < 0.5) {
+        recommendations.push({
+          componentName: metric.componentName,
+          type: "decrease_ttl",
+          description: `Reduce cache size for ${metric.componentName} components`,
+          expectedImprovement: 15,
+          priority: 3,
+          reasoning: `High memory usage (${(metric.memoryUsage / 1024 / 1024).toFixed(2)}MB) with moderate hit rate suggests over-caching.`
+        });
+      }
+      if (metric.efficiencyScore < 30) {
+        recommendations.push({
+          componentName: metric.componentName,
+          type: "disable_cache",
+          description: `Consider disabling cache for ${metric.componentName} components`,
+          expectedImprovement: 10,
+          priority: 2,
+          reasoning: `Efficiency score of ${metric.efficiencyScore} indicates caching may not be beneficial for this component.`
+        });
+      }
+      if (trend && this.isDecliningSlopbankTrend(trend.hitRateTrend)) {
+        recommendations.push({
+          componentName: metric.componentName,
+          type: "increase_size",
+          description: `Increase cache capacity for ${metric.componentName} components`,
+          expectedImprovement: 25,
+          priority: 5,
+          reasoning: "Hit rate is declining over time, suggesting cache capacity may be insufficient."
+        });
+      }
+    });
+    return recommendations.sort((a, b) => b.priority - a.priority);
+  }
+  /**
+   * Check if a trend is declining
+   */
+  isDecliningSlopbankTrend(trend) {
+    if (trend.length < 3) return false;
+    const n = trend.length;
+    const recent = trend.slice(-Math.min(10, n));
+    if (recent.length < 3) return false;
+    const firstValue = recent[0].value;
+    const lastValue = recent[recent.length - 1].value;
+    return (firstValue - lastValue) / firstValue > 0.1;
+  }
+  /**
+   * Calculate overall cache health score
+   */
+  calculateHealthScore(metrics) {
+    if (metrics.length === 0) return 0;
+    const avgEfficiency = metrics.reduce((sum, m) => sum + m.efficiencyScore, 0) / metrics.length;
+    const avgHitRate = metrics.reduce((sum, m) => sum + m.hitRate, 0) / metrics.length;
+    const healthScore = avgEfficiency * 0.6 + avgHitRate * 100 * 0.4;
+    return Math.round(healthScore);
+  }
+  /**
+   * Calculate overall cache efficiency
+   */
+  calculateOverallEfficiency(metrics) {
+    if (metrics.length === 0) return 0;
+    const totalTimeSaved = metrics.reduce((sum, m) => sum + m.timeSaved, 0);
+    const totalMemoryUsed = metrics.reduce((sum, m) => sum + m.memoryUsage, 0);
+    const totalRequests = metrics.reduce((sum, m) => sum + m.totalRequests, 0);
+    const totalHits = metrics.reduce(
+      (sum, m) => sum + m.hitRate * m.totalRequests,
+      0
+    );
+    if (totalRequests === 0) return 0;
+    const hitRateEfficiency = totalHits / totalRequests * 100;
+    const resourceEfficiency = totalMemoryUsed > 0 ? Math.min(100, totalTimeSaved / totalMemoryUsed * 1e3) : 0;
+    return Math.round(hitRateEfficiency * 0.7 + resourceEfficiency * 0.3);
+  }
+  /**
+   * Calculate performance gain from caching
+   */
+  calculatePerformanceGain(metrics) {
+    const totalTimeSaved = metrics.reduce((sum, m) => sum + m.timeSaved, 0);
+    const totalProcessingTime = metrics.reduce(
+      (sum, m) => sum + m.totalRequests * m.avgMissTime,
+      0
+    );
+    const cpuReduction = totalProcessingTime > 0 ? Math.round(totalTimeSaved / totalProcessingTime * 100) : 0;
+    const uniqueEntries = metrics.reduce(
+      (sum, m) => sum + m.memoryUsage / m.avgHitTime,
+      0
+    );
+    const totalDataProcessed = metrics.reduce(
+      (sum, m) => sum + m.totalRequests * m.memoryUsage,
+      0
+    );
+    const memoryOptimization = totalDataProcessed > 0 ? Math.round(
+      (totalDataProcessed - uniqueEntries) / totalDataProcessed * 100
+    ) : 0;
+    return {
+      timeReduction: Math.round(totalTimeSaved),
+      cpuReduction: Math.min(100, cpuReduction),
+      memoryOptimization: Math.min(100, memoryOptimization)
+    };
+  }
+  /**
+   * Reset analytics history
+   */
+  reset() {
+    this.metricsHistory.clear();
+    this.performanceBaseline.clear();
+  }
+};
+export {
+  ComponentCacheAnalytics,
+  ComponentCacheManager,
+  DEFAULT_CACHE_CONFIG,
+  MemoryCache,
+  getCacheConfigFromEnv,
+  mergeConfigs
+};
+//# sourceMappingURL=index.js.map