@json-to-office/shared 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 Wiseair srl
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
+associated documentation files (the "Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT
+LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,9 @@
+# @json-to-office/shared
+
+Format-agnostic shared types, schemas and validation utilities.
+
+> **Internal package** — used by other @json-to-office packages. You probably want [`@json-to-office/json-to-docx`](../json-to-docx) or [`@json-to-office/json-to-pptx`](../json-to-pptx) instead.
+
+## License
+
+[MIT](../../LICENSE)

package/dist/cache/index.d.ts

@@ -0,0 +1,464 @@
+import { EventEmitter } from 'events';
+
+/**
+ * Cache Types and Interfaces
+ * Core type definitions for the component caching system
+ */
+/**
+ * Cache entry metadata
+ */
+interface CacheMetadata {
+    /** Creation timestamp */
+    timestamp: number;
+    /** Number of cache hits */
+    hits: number;
+    /** Size in bytes */
+    size: number;
+    /** Component dependencies */
+    dependencies: string[];
+    /** Content signature for validation */
+    signature: string;
+    /** Time-to-live in seconds */
+    ttl?: number;
+    /** Last access timestamp */
+    lastAccessed: number;
+}
+/**
+ * Cached component entry
+ */
+interface CachedComponent extends CacheMetadata {
+    /** Processed component result */
+    result: unknown;
+    /** Component name for analytics */
+    componentName: string;
+    /** Original component props hash */
+    propsHash: string;
+}
+/**
+ * Cache statistics
+ */
+interface CacheStatistics {
+    /** Total number of entries */
+    entries: number;
+    /** Total cache size in bytes */
+    totalSize: number;
+    /** Cache hit rate (0-1) */
+    hitRate: number;
+    /** Cache miss rate (0-1) */
+    missRate: number;
+    /** Total hits */
+    totalHits: number;
+    /** Total misses */
+    totalMisses: number;
+    /** Average response time in ms */
+    avgResponseTime: number;
+    /** Eviction count */
+    evictions: number;
+    /** Per-component statistics */
+    componentStats: Map<string, ComponentStatistics>;
+}
+/**
+ * Component-specific statistics
+ */
+interface ComponentStatistics {
+    /** Component name */
+    name: string;
+    /** Number of cache hits */
+    hits: number;
+    /** Number of cache misses */
+    misses: number;
+    /** Average processing time when missed */
+    avgProcessTime: number;
+    /** Average size of cached entries */
+    avgSize: number;
+    /** Number of cached entries */
+    entries: number;
+}
+/**
+ * Cache key options
+ */
+interface CacheKeyOptions {
+    /** Include theme in key generation */
+    includeTheme?: boolean;
+    /** Include render context in key */
+    includeContext?: boolean;
+    /** Additional key components */
+    additionalKeys?: string[];
+    /** Key version for cache busting */
+    version?: string;
+}
+/**
+ * Cache configuration
+ */
+interface CacheConfiguration {
+    /** Enable/disable caching globally */
+    enabled: boolean;
+    /** Memory cache configuration */
+    memory: {
+        enabled: boolean;
+        /** Maximum cache size in MB */
+        maxSize: number;
+        /** Maximum number of entries */
+        maxEntries: number;
+        /** Default TTL in seconds */
+        defaultTTL: number;
+        /** Check expired entries interval in seconds */
+        cleanupInterval: number;
+    };
+    /** Disk cache configuration (future) */
+    disk?: {
+        enabled: boolean;
+        /** Cache directory path */
+        path: string;
+        /** Maximum cache size in MB */
+        maxSize: number;
+        /** Default TTL in seconds */
+        defaultTTL: number;
+        /** Compression enabled */
+        compression: boolean;
+    };
+    /** Eviction policy */
+    evictionPolicy: 'lru' | 'lfu' | 'fifo' | 'ttl';
+    /** Component-specific configurations */
+    componentConfig?: {
+        [componentName: string]: {
+            /** Whether this component is cacheable */
+            cacheable: boolean;
+            /** Custom TTL for this component */
+            ttl?: number;
+            /** Maximum entries for this component */
+            maxEntries?: number;
+        };
+    };
+    /** Performance settings */
+    performance: {
+        /** Enable performance tracking */
+        trackMetrics: boolean;
+        /** Metrics sampling rate (0-1) */
+        metricsSampleRate: number;
+        /** Enable cache warming */
+        enableWarming: boolean;
+        /** Parallel processing for batch operations */
+        parallelProcessing: boolean;
+    };
+}
+/**
+ * Cache events for monitoring
+ */
+interface CacheEvents {
+    hit: (key: string, component: CachedComponent) => void;
+    miss: (key: string) => void;
+    set: (key: string, component: CachedComponent) => void;
+    evict: (key: string, reason: 'ttl' | 'size' | 'manual') => void;
+    error: (error: Error) => void;
+    stats: (stats: CacheStatistics) => void;
+}
+
+/**
+ * Cache Manager Base Class
+ * Abstract base class for cache implementations
+ */
+
+/**
+ * Main cache manager abstract class
+ */
+declare abstract class ComponentCacheManager extends EventEmitter {
+    protected config: CacheConfiguration;
+    protected stats: CacheStatistics;
+    constructor(config: CacheConfiguration);
+    /**
+     * Get a cached component
+     */
+    abstract get(key: string): Promise<CachedComponent | undefined>;
+    /**
+     * Set a cached component
+     */
+    abstract set(key: string, component: CachedComponent): Promise<void>;
+    /**
+     * Check if key exists
+     */
+    abstract has(key: string): Promise<boolean>;
+    /**
+     * Delete a cached entry
+     */
+    abstract delete(key: string): Promise<boolean>;
+    /**
+     * Clear all cache entries
+     */
+    abstract clear(): Promise<void>;
+    /**
+     * Get all keys (for utilities)
+     */
+    abstract getKeys(): Promise<string[]>;
+    /**
+     * Get cache statistics with deep immutability
+     */
+    getStats(): CacheStatistics;
+    /**
+     * Get configuration with deep immutability
+     */
+    getConfig(): CacheConfiguration;
+    /**
+     * Get multiple entries (batch operation)
+     */
+    getMany(keys: string[]): Promise<Map<string, CachedComponent>>;
+    /**
+     * Set multiple entries (batch operation)
+     */
+    setMany(entries: [string, CachedComponent][]): Promise<void>;
+    /**
+     * Delete multiple entries
+     */
+    deleteMany(keys: string[]): Promise<number>;
+    /**
+     * Initialize statistics
+     */
+    protected initializeStats(): CacheStatistics;
+    /**
+     * Update statistics on cache hit
+     */
+    protected updateHitStats(key: string, component: CachedComponent): void;
+    /**
+     * Update statistics on cache miss
+     */
+    protected updateMissStats(key: string, componentName?: string): void;
+    /**
+     * Update component-specific statistics
+     */
+    protected updateComponentStats(componentName: string, event: 'hit' | 'miss'): void;
+    /**
+     * Recalculate hit/miss rates
+     */
+    protected recalculateRates(): void;
+    /**
+     * Emit statistics periodically
+     */
+    protected emitStats(): void;
+}
+
+/**
+ * Memory Cache Implementation
+ * In-memory cache with LRU eviction policy
+ */
+
+/**
+ * In-memory cache with LRU eviction
+ */
+declare class MemoryCache extends ComponentCacheManager {
+    private cache;
+    private head;
+    private tail;
+    private currentSize;
+    private keyToComponentName;
+    private cleanupTimer?;
+    constructor(config: CacheConfiguration);
+    get(key: string): Promise<CachedComponent | undefined>;
+    set(key: string, component: CachedComponent): Promise<void>;
+    has(key: string): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+    clear(): Promise<void>;
+    getKeys(): Promise<string[]>;
+    /**
+     * Extract component name from cache key
+     */
+    private extractComponentNameFromKey;
+    /**
+     * Check if component is expired
+     */
+    private isExpired;
+    /**
+     * Check if component is cacheable
+     */
+    private isCacheable;
+    /**
+     * Ensure enough space for new entry
+     */
+    private ensureSpace;
+    /**
+     * LRU operations - Add node to head
+     */
+    private addToHead;
+    /**
+     * Remove node from list
+     */
+    private removeNode;
+    /**
+     * Move node to head
+     */
+    private moveToHead;
+    /**
+     * Start cleanup timer for expired entries
+     */
+    private startCleanupTimer;
+    /**
+     * Stop cleanup timer
+     */
+    destroy(): void;
+}
+
+/**
+ * Cache Configuration
+ * Default configuration and environment-based configuration
+ */
+
+/**
+ * Default cache configuration
+ */
+declare const DEFAULT_CACHE_CONFIG: CacheConfiguration;
+/**
+ * Get cache configuration from environment variables
+ */
+declare function getCacheConfigFromEnv(): Partial<CacheConfiguration>;
+/**
+ * Merge configurations with priority
+ */
+declare function mergeConfigs(...configs: Partial<CacheConfiguration>[]): CacheConfiguration;
+
+/**
+ * Component Cache Analytics
+ * Advanced analytics and insights for component-level caching
+ */
+
+/**
+ * Time-series data point for tracking metrics over time
+ */
+interface TimeSeriesPoint {
+    timestamp: number;
+    value: number;
+}
+/**
+ * Component performance metrics
+ */
+interface ComponentPerformanceMetrics {
+    /** Component name identifier */
+    componentName: string;
+    /** Cache hit rate (0-1) */
+    hitRate: number;
+    /** Total requests (hits + misses) */
+    totalRequests: number;
+    /** Average response time for cache hits (ms) */
+    avgHitTime: number;
+    /** Average response time for cache misses (ms) */
+    avgMissTime: number;
+    /** Cache efficiency score (0-100) */
+    efficiencyScore: number;
+    /** Memory usage in bytes */
+    memoryUsage: number;
+    /** Time saved by caching (ms) */
+    timeSaved: number;
+    /** Cost-benefit ratio */
+    costBenefitRatio: number;
+}
+/**
+ * Component cache trends over time
+ */
+interface ComponentCacheTrends {
+    /** Component name */
+    componentName: string;
+    /** Hit rate trend */
+    hitRateTrend: TimeSeriesPoint[];
+    /** Request volume trend */
+    requestVolumeTrend: TimeSeriesPoint[];
+    /** Response time trend */
+    responseTimeTrend: TimeSeriesPoint[];
+    /** Memory usage trend */
+    memoryUsageTrend: TimeSeriesPoint[];
+}
+/**
+ * Cache optimization recommendations
+ */
+interface CacheOptimizationRecommendation {
+    /** Component name to optimize */
+    componentName: string;
+    /** Recommendation type */
+    type: 'increase_ttl' | 'decrease_ttl' | 'increase_size' | 'disable_cache' | 'enable_cache';
+    /** Recommendation description */
+    description: string;
+    /** Expected improvement percentage */
+    expectedImprovement: number;
+    /** Priority level (1-5, 5 being highest) */
+    priority: number;
+    /** Detailed reasoning */
+    reasoning: string;
+}
+/**
+ * Comprehensive cache analytics report
+ */
+interface CacheAnalyticsReport {
+    /** Report generation timestamp */
+    timestamp: number;
+    /** Overall cache health score (0-100) */
+    healthScore: number;
+    /** Total cache efficiency percentage */
+    overallEfficiency: number;
+    /** Per-component performance metrics */
+    componentMetrics: ComponentPerformanceMetrics[];
+    /** Component cache trends */
+    trends: ComponentCacheTrends[];
+    /** Optimization recommendations */
+    recommendations: CacheOptimizationRecommendation[];
+    /** Top performing components */
+    topPerformers: string[];
+    /** Components needing attention */
+    needsAttention: string[];
+    /** Estimated performance gain from caching */
+    performanceGain: {
+        timeReduction: number;
+        cpuReduction: number;
+        memoryOptimization: number;
+    };
+}
+/**
+ * Component Cache Analytics Engine
+ */
+declare class ComponentCacheAnalytics {
+    private historyWindow;
+    private metricsHistory;
+    private performanceBaseline;
+    /**
+     * Analyze cache statistics and generate comprehensive report
+     */
+    analyzeCache(stats: CacheStatistics): CacheAnalyticsReport;
+    /**
+     * Calculate detailed metrics for each component
+     */
+    private calculateComponentMetrics;
+    /**
+     * Calculate efficiency score for a component
+     */
+    private calculateEfficiencyScore;
+    /**
+     * Calculate trends over time
+     */
+    private calculateTrends;
+    /**
+     * Get or create history for a metric
+     */
+    private getOrCreateHistory;
+    /**
+     * Generate optimization recommendations
+     */
+    private generateRecommendations;
+    /**
+     * Check if a trend is declining
+     */
+    private isDecliningSlopbankTrend;
+    /**
+     * Calculate overall cache health score
+     */
+    private calculateHealthScore;
+    /**
+     * Calculate overall cache efficiency
+     */
+    private calculateOverallEfficiency;
+    /**
+     * Calculate performance gain from caching
+     */
+    private calculatePerformanceGain;
+    /**
+     * Reset analytics history
+     */
+    reset(): void;
+}
+
+export { type CacheAnalyticsReport, type CacheConfiguration, type CacheEvents, type CacheKeyOptions, type CacheMetadata, type CacheOptimizationRecommendation, type CacheStatistics, type CachedComponent, ComponentCacheAnalytics, ComponentCacheManager, type ComponentCacheTrends, type ComponentPerformanceMetrics, type ComponentStatistics, DEFAULT_CACHE_CONFIG, MemoryCache, type TimeSeriesPoint, getCacheConfigFromEnv, mergeConfigs };