@fjell/cache 4.7.40 → 4.7.41

package/dist/ttl/TTLCalculator.d.ts

@@ -0,0 +1,96 @@
+/**
+ * TTL Calculator - Smart TTL calculation with context awareness
+ *
+ * Calculates appropriate TTLs based on:
+ * - Item/query types
+ * - Peak hours adjustments
+ * - Stale-while-revalidate thresholds
+ */
+import { TTLConfig } from './TTLConfig.js';
+export interface TTLCalculationContext {
+    /** Item type for item-level TTL calculation */
+    itemType?: string;
+    /** Query type for query-level TTL calculation */
+    queryType?: string;
+    /** Whether this is a complete data set */
+    isComplete?: boolean;
+    /** Override timestamp for calculation (useful for testing) */
+    timestamp?: Date;
+}
+export interface TTLResult {
+    /** Calculated TTL in seconds */
+    ttl: number;
+    /** Original base TTL before adjustments */
+    baseTTL: number;
+    /** Applied adjustments */
+    adjustments: {
+        peakHours?: {
+            applied: boolean;
+            multiplier: number;
+        };
+    };
+    /** Stale threshold in seconds (80% of TTL) */
+    staleThreshold: number;
+}
+export declare class TTLCalculator {
+    private config;
+    constructor(config: TTLConfig);
+    /**
+     * Calculate TTL for an individual item
+     */
+    calculateItemTTL(itemType: string, context?: TTLCalculationContext): TTLResult;
+    /**
+     * Calculate TTL for a query result
+     */
+    calculateQueryTTL(queryType: string, isComplete: boolean, context?: TTLCalculationContext): TTLResult;
+    /**
+     * Calculate TTL with full context
+     */
+    calculateContextualTTL(context: TTLCalculationContext): TTLResult;
+    /**
+     * Check if cached data is stale (but not expired)
+     */
+    isStale(createdAt: Date, ttl: number, timestamp?: Date): boolean;
+    /**
+     * Check if cached data is expired
+     */
+    isExpired(createdAt: Date, ttl: number, timestamp?: Date): boolean;
+    /**
+     * Calculate when data will become stale
+     */
+    calculateStaleTime(createdAt: Date, ttl: number): Date;
+    /**
+     * Calculate when data will expire
+     */
+    calculateExpirationTime(createdAt: Date, ttl: number): Date;
+    /**
+     * Apply dynamic adjustments to base TTL
+     */
+    private applyAdjustments;
+    /**
+     * Apply peak hours TTL reduction
+     */
+    private applyPeakHoursAdjustment;
+    /**
+     * Get recommended TTL for common scenarios
+     */
+    getRecommendedTTL(scenario: 'realtime' | 'normal' | 'static'): {
+        item: number;
+        query: {
+            complete: number;
+            faceted: number;
+        };
+    };
+    /**
+     * Calculate optimal TTL based on data volatility
+     */
+    calculateAdaptiveTTL(baseType: string, recentChangeFrequency: number): number;
+    /**
+     * Debug information about TTL calculation
+     */
+    explainTTLCalculation(context: TTLCalculationContext): {
+        result: TTLResult;
+        explanation: string[];
+    };
+}
+//# sourceMappingURL=TTLCalculator.d.ts.map

package/dist/ttl/TTLCalculator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TTLCalculator.d.ts","sourceRoot":"","sources":["../../src/ttl/TTLCalculator.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,MAAM,WAAW,qBAAqB;IACpC,+CAA+C;IAC/C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iDAAiD;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,GAAG,EAAE,MAAM,CAAC;IACZ,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,0BAA0B;IAC1B,WAAW,EAAE;QACX,SAAS,CAAC,EAAE;YACV,OAAO,EAAE,OAAO,CAAC;YACjB,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;KACH,CAAC;IACF,8CAA8C;IAC9C,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,qBAAa,aAAa;IACZ,OAAO,CAAC,MAAM;gBAAN,MAAM,EAAE,SAAS;IAErC;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,qBAAqB,GAAG,SAAS;IAY9E;;OAEG;IACH,iBAAiB,CACf,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,OAAO,EACnB,OAAO,CAAC,EAAE,qBAAqB,GAC9B,SAAS;IAoBZ;;OAEG;IACH,sBAAsB,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS;IAcjE;;OAEG;IACH,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,OAAO;IAShE;;OAEG;IACH,SAAS,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,IAAI,GAAG,OAAO;IAQlE;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAKtD;;OAEG;IACH,uBAAuB,CAAC,SAAS,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI;IAI3D;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsBxB;;OAEG;IACH,OAAO,CAAC,wBAAwB;IAqChC;;OAEG;IACH,iBAAiB,CAAC,QAAQ,EAAE,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG;QAC7D,IAAI,EAAE,MAAM,CAAC;QACb,KAAK,EAAE;YAAE,QAAQ,EAAE,MAAM,CAAC;YAAC,OAAO,EAAE,MAAM,CAAA;SAAE,CAAC;KAC9C;IAsBD;;OAEG;IACH,oBAAoB,CAClB,QAAQ,EAAE,MAAM,EAChB,qBAAqB,EAAE,MAAM,GAC5B,MAAM;IAgBT;;OAEG;IACH,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG;QACrD,MAAM,EAAE,SAAS,CAAC;QAClB,WAAW,EAAE,MAAM,EAAE,CAAC;KACvB;CAsCF"}

package/dist/ttl/TTLConfig.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Enhanced TTL Configuration System
+ *
+ * Provides sophisticated TTL management with per-type configurations,
+ * peak hours adjustments, and stale-while-revalidate patterns.
+ */
+export interface TTLConfig {
+    /** Item-level TTL configuration */
+    item: {
+        /** Default TTL for all items (seconds) */
+        default: number;
+        /** Per-type TTL overrides (seconds) */
+        byType?: Record<string, number>;
+    };
+    /** Query-level TTL configuration */
+    query: {
+        /** TTL for complete data sets (seconds) */
+        complete: number;
+        /** TTL for filtered/faceted results (seconds) */
+        faceted: number;
+        /** Per-facet type TTL overrides (seconds) */
+        byFacet?: Record<string, number>;
+    };
+    /** Dynamic TTL adjustments */
+    adjustments?: {
+        /** Reduce TTL during peak usage hours */
+        peakHours?: {
+            /** Start hour (0-23) */
+            start: number;
+            /** End hour (0-23) */
+            end: number;
+            /** TTL multiplier during peak hours (e.g., 0.5 for half TTL) */
+            multiplier: number;
+        };
+        /** Enable stale-while-revalidate pattern */
+        staleWhileRevalidate?: boolean;
+        /** Timezone for peak hours calculation (default: system timezone) */
+        timezone?: string;
+    };
+    /** Cache warming configuration */
+    warming?: {
+        /** Enable automatic cache warming */
+        enabled: boolean;
+        /** Interval between warming cycles (milliseconds) */
+        interval: number;
+        /** Common queries to warm */
+        queries: WarmingQuery[];
+    };
+}
+/** Configuration for cache warming */
+export interface WarmingQuery {
+    /** Query parameters */
+    params: any;
+    /** Priority (1-10, higher = more important) */
+    priority: number;
+    /** TTL multiplier for warmed data (optional) */
+    ttlMultiplier?: number;
+}
+/**
+ * Default TTL configuration optimized for typical usage patterns
+ */
+export declare const defaultTTLConfig: TTLConfig;
+/**
+ * TTL configuration for high-traffic scenarios
+ */
+export declare const highTrafficTTLConfig: TTLConfig;
+/**
+ * TTL configuration for development/testing
+ */
+export declare const developmentTTLConfig: TTLConfig;
+/**
+ * Validates TTL configuration for common issues
+ */
+export declare function validateTTLConfig(config: TTLConfig): string[];
+/**
+ * Creates a TTL config with sensible defaults merged with user overrides
+ */
+export declare function createTTLConfig(overrides?: Partial<TTLConfig>): TTLConfig;
+//# sourceMappingURL=TTLConfig.d.ts.map

package/dist/ttl/TTLConfig.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TTLConfig.d.ts","sourceRoot":"","sources":["../../src/ttl/TTLConfig.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,SAAS;IACxB,mCAAmC;IACnC,IAAI,EAAE;QACJ,0CAA0C;QAC1C,OAAO,EAAE,MAAM,CAAC;QAChB,uCAAuC;QACvC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACjC,CAAC;IAEF,oCAAoC;IACpC,KAAK,EAAE;QACL,2CAA2C;QAC3C,QAAQ,EAAE,MAAM,CAAC;QACjB,iDAAiD;QACjD,OAAO,EAAE,MAAM,CAAC;QAChB,6CAA6C;QAC7C,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,CAAC;IAEF,8BAA8B;IAC9B,WAAW,CAAC,EAAE;QACZ,yCAAyC;QACzC,SAAS,CAAC,EAAE;YACV,wBAAwB;YACxB,KAAK,EAAE,MAAM,CAAC;YACd,sBAAsB;YACtB,GAAG,EAAE,MAAM,CAAC;YACZ,gEAAgE;YAChE,UAAU,EAAE,MAAM,CAAC;SACpB,CAAC;QACF,4CAA4C;QAC5C,oBAAoB,CAAC,EAAE,OAAO,CAAC;QAC/B,qEAAqE;QACrE,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IAEF,kCAAkC;IAClC,OAAO,CAAC,EAAE;QACR,qCAAqC;QACrC,OAAO,EAAE,OAAO,CAAC;QACjB,qDAAqD;QACrD,QAAQ,EAAE,MAAM,CAAC;QACjB,6BAA6B;QAC7B,OAAO,EAAE,YAAY,EAAE,CAAC;KACzB,CAAC;CACH;AAED,sCAAsC;AACtC,MAAM,WAAW,YAAY;IAC3B,uBAAuB;IACvB,MAAM,EAAE,GAAG,CAAC;IACZ,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB,gDAAgD;IAChD,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAgD9B,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,SAoBlC,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,SA0BlC,CAAC;AAEF;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,CAoC7D;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,SAAS,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAiC7E"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fjell/cache",
   "description": "Cache for Fjell",
-  "version": "4.7.40",
+  "version": "4.7.41",
   "keywords": [
     "cache",
     "fjell"