cds-caching 0.3.3 → 1.0.0

package/cds-plugin.js

@@ -1,6 +1,6 @@
 const cds = require('@sap/cds')
-const CachingService = require('./srv/CachingService')
-const { scanCachingAnnotations } = require('./srv/util')
+const CachingService = require('./lib/CachingService')
+const { scanCachingAnnotations } = require('./lib/util')
 
 cds.on('served', scanCachingAnnotations)
 

package/index.cds

@@ -1,21 +1,166 @@
-namespace cds_caching;
-
-entity Statistics {
-    key ID          : String; // e.g., 'daily:2024-03-20' or 'hourly:2024-03-20-15'
-    key cache       : String;
-        timestamp   : DateTime;
-        period      : String enum {
-            hourly;
-            daily;
-            monthly;
-        }; // Granularity
-        hits        : Integer default 0;
-        misses      : Integer default 0;
-        sets        : Integer default 0;
-        deletes     : Integer default 0;
-        errors      : Integer default 0;
-        avgLatency  : Double; // in milliseconds
-        p95Latency  : Double; // 95th percentile latency
-        memoryUsage : Integer; // in bytes
-        itemCount   : Integer;
+context plugin.cds_caching {
+
+    entity Caches {
+        key name              : String;
+            config            : String;
+            metricsEnabled    : Boolean default false;
+            keyMetricsEnabled : Boolean default false;
+            metrics           : Composition of many Metrics
+                                    on metrics.cache = $self.name;
+            keyMetrics        : Composition of many KeyMetrics
+                                    on keyMetrics.cache = $self.name;
+    }
+
+    entity Metrics {
+        key ID                    : String; // e.g., 'daily:2024-03-20' or 'hourly:2024-03-20-15'
+        key cache                 : String;
+            timestamp             : DateTime;
+            period                : String enum {
+                hourly;
+                daily;
+                monthly;
+            }; // Granularity
+
+            // Read-through metrics (hits and misses only)
+            hits                  : Integer default 0;
+            misses                : Integer default 0;
+            errors                : Integer default 0;
+            totalRequests         : Integer default 0;
+            // Read-through latency metrics
+            avgHitLatency         : Double; // average hit latency in milliseconds
+            minHitLatency         : Double; // minimum hit latency
+            maxHitLatency         : Double; // maximum hit latency
+            avgMissLatency        : Double; // average miss latency in milliseconds
+            minMissLatency        : Double; // minimum miss latency
+            maxMissLatency        : Double; // maximum miss latency
+            avgReadThroughLatency : Double; // average read through latency in milliseconds
+
+            // Read-through performance metrics
+            hitRatio              : Double; // hit ratio as percentage
+            throughput            : Double; // requests per second
+            errorRate             : Double; // error rate as percentage
+            cacheEfficiency       : Double; // ratio of miss latency to hit latency
+
+            // Native function metrics (basic counts only)
+            nativeSets            : Integer default 0;
+            nativeGets            : Integer default 0;
+            nativeDeletes         : Integer default 0;
+            nativeClears          : Integer default 0;
+            nativeDeleteByTags    : Integer default 0;
+            nativeErrors          : Integer default 0;
+            totalNativeOperations : Integer default 0;
+            // Native function performance metrics
+            nativeThroughput      : Double; // native operations per second
+            nativeErrorRate       : Double; // native operation error rate
+
+            // Common metrics
+            memoryUsage           : Integer; // in bytes
+            itemCount             : Integer;
+            uptimeMs              : Integer; // uptime in milliseconds
+    }
+
+    entity KeyMetrics {
+        key ID                    : String;
+        key cache                 : String;
+        key keyName               : String;
+            lastAccess            : DateTime;
+            period                : String enum {
+                current;
+                hourly;
+                daily;
+            };
+
+            // Operation type tracking
+            operationType         : String enum {
+                read_through;
+                native;
+                mixed;
+            };
+
+            // Read-through metrics (hits and misses only)
+            hits                  : Integer default 0;
+            misses                : Integer default 0;
+            errors                : Integer default 0;
+            totalRequests         : Integer default 0;
+            hitRatio              : Double; // hit ratio as percentage
+            cacheEfficiency       : Double; // ratio of miss latency to hit latency
+
+            // Read-through latency metrics
+            avgHitLatency         : Double; // average hit latency in milliseconds
+            minHitLatency         : Double; // minimum hit latency
+            maxHitLatency         : Double; // maximum hit latency
+            avgMissLatency        : Double; // average miss latency in milliseconds
+            minMissLatency        : Double; // minimum miss latency
+            maxMissLatency        : Double; // maximum miss latency
+            avgReadThroughLatency : Double; // average read through latency in milliseconds
+
+            // Read-through performance metrics
+            throughput            : Double; // requests per second
+            errorRate             : Double; // error rate as percentage
+
+            // Native function metrics (counts only)
+            nativeHits            : Integer default 0;
+            nativeMisses          : Integer default 0;
+            nativeSets            : Integer default 0;
+            nativeDeletes         : Integer default 0;
+            nativeClears          : Integer default 0;
+            nativeDeleteByTags    : Integer default 0;
+            nativeErrors          : Integer default 0;
+            totalNativeOperations : Integer default 0;
+            // Native function performance metrics
+            nativeThroughput      : Double; // native operations per second
+            nativeErrorRate       : Double; // native operation error rate
+
+            // Metadata fields
+            dataType              : String;
+            operation             : String; // concatenated cache service operations (e.g., SET, GET, WRAP, RUN...)
+            metadata              : LargeString; // JSON string for additional metadata
+            // Enhanced context information
+            context               : String; // JSON string with detailed context
+            query                 : LargeString; // CQL query text if applicable
+            subject               : LargeString; // JSON string with subject information
+            target                : String; // Target information
+            tenant                : String; // Tenant information
+            user                  : String; // User information
+            locale                : String; // Locale information
+            timestamp             : DateTime; // When this key was first accessed
+            cacheOptions          : String; // JSON string with cache options
+    }
+
+
+    @impl: 'cds-caching/srv/caching-api-service'
+    service CachingApiService {
+
+        entity Caches     as projection on plugin.cds_caching.Caches
+            actions {
+
+                function getEntries()                                          returns array of {
+                    entryKey  : String;
+                    value     : String;
+                    timestamp : DateTime;
+                    tags      : array of String;
+                };
+
+                function getEntry(key : String)                                returns {
+                    value     : String;
+                    timestamp : DateTime;
+                    tags      : array of String;
+                };
+
+                action   setEntry(key : String, value : String, ttl : Integer) returns Boolean;
+                action   deleteEntry(key : String)                             returns Boolean;
+                action   clear()                                               returns Boolean;
+                action   clearMetrics()                                        returns Boolean;
+                action   clearKeyMetrics()                                     returns Boolean;
+                action   setMetricsEnabled(enabled : Boolean)                  returns Boolean;
+                action   setKeyMetricsEnabled(enabled : Boolean)               returns Boolean;
+            };
+
+        @readonly
+        entity Metrics    as projection on plugin.cds_caching.Metrics;
+
+        @readonly
+        entity KeyMetrics as projection on plugin.cds_caching.KeyMetrics;
+
+    }
 }

package/lib/CachingService.d.ts

@@ -0,0 +1,328 @@
+import { Service, cds } from '@sap/cds';
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+export interface CacheTag {
+  template: string;
+  data?: string;
+  prefix?: string;
+  suffix?: string;
+  value?: string; 
+}
+
+export interface CacheOptions {
+  ttl?: number;
+  tags?: CacheTag[] | string[];
+  key?: string | object;
+  params?: Record<string, any>;
+}
+
+export interface CacheMetadata {
+  value: any;
+  tags: CacheTag[]; 
+  timestamp: number;
+}
+
+export interface StatisticsMetadata {
+  dataType: string;
+  serviceName: string;
+  operation: string;
+  metadata: string;
+  entityName?: string;
+  queryInfo?: string;
+}
+
+export interface RuntimeConfiguration {
+  enableStatistics: boolean;
+  enableKeyTracking: boolean;
+}
+
+export interface CacheStatistics {
+  hits: number;
+  misses: number;
+  totalRequests: number;
+  hitRate: number;
+  averageLatency: number;
+  totalLatency: number;
+}
+
+export interface CacheKeyMetrics {
+  key: string;
+  hits: number;
+  misses: number;
+  totalRequests: number;
+  hitRate: number;
+  averageLatency: number;
+  lastAccessed: Date;
+}
+
+export interface CachableFunctionOptions {
+  '@cache.ttl'?: number;
+  '@cache.key'?: string | object;
+  '@cache.tags'?: string[];
+}
+
+export interface ReadThroughResult<T = any> {
+  result: T;
+  cacheKey: string;
+  metadata: {
+    hit: boolean;
+    latency: number;
+  };
+}
+
+export interface CacheAnnotatedFunction {
+  name: string;
+  options: CachableFunctionOptions;
+}
+
+// ============================================================================
+// Read Through Operations Interface
+// ============================================================================
+
+export interface ReadThroughOperations {
+  /**
+   * Send a request with caching with read-through capabilities
+   */
+  send(request: any, service: Service, options?: CacheOptions): Promise<ReadThroughResult>;
+
+  /**
+   * Run a cached operation with automatic key generation
+   */
+  run(req: any, service: Service, options?: CacheOptions): Promise<ReadThroughResult>;
+
+  /**
+   * Wraps an async function and caches the result
+   */
+  wrap<T extends (...args: any[]) => Promise<any>>(
+    key: string,
+    asyncFunction: T,
+    options?: CacheOptions
+  ): (...args: Parameters<T>) => Promise<ReadThroughResult<Awaited<ReturnType<T>>>>;
+
+  /**
+   * Executes an async function and caches its result
+   */
+  exec<T>(
+    key: string,
+    asyncFunction: () => Promise<T>,
+    options?: CacheOptions
+  ): Promise<ReadThroughResult<T>>;
+}
+
+// ============================================================================
+// CachingService Class Definition
+// ============================================================================
+
+export declare class CachingService extends Service {
+  // Properties
+  readonly name: string;
+  readonly options: {
+    store: any;
+    compression: any;
+    credentials: Record<string, any>;
+    namespace?: string;
+  };
+  
+  private cacheAnnotatedFunctions: {
+    bound: CacheAnnotatedFunction[];
+    unbound: CacheAnnotatedFunction[];
+  };
+
+  // Read-through operations
+  readonly rt: ReadThroughOperations;
+
+  // ============================================================================
+  // Core Cache Operations
+  // ============================================================================
+
+  /**
+   * Create a cache key from various inputs
+   */
+  createKey(...args: any[]): string;
+
+  /**
+   * Set a value in the cache
+   */
+  set(key: string | object, value: any, options?: CacheOptions): Promise<void>;
+
+  /**
+   * Get a value from the cache
+   */
+  get(key: string | object): Promise<any>;
+
+  /**
+   * Check if a key exists in the cache
+   */
+  has(key: string | object): Promise<boolean>;
+
+  /**
+   * Delete a key from the cache
+   */
+  delete(key: string | object): Promise<boolean>;
+
+  /**
+   * Clear all cache entries
+   */
+  clear(): Promise<void>;
+
+  /**
+   * Delete all keys that have a specific tag
+   */
+  deleteByTag(tag: string): Promise<void>;
+
+  /**
+   * Get metadata for a key
+   */
+  metadata(key: string | object): Promise<CacheMetadata | null>;
+
+  /**
+   * Get tags for a key
+   */
+  tags(key: string | object): Promise<string[]>;
+
+  /**
+   * Iterator for all cache entries
+   */
+  iterator(): AsyncIterableIterator<[string, CacheMetadata]>;
+
+  /**
+   * Get a raw value from the cache without statistics tracking
+   */
+  getRaw(key: string | object): Promise<any>;
+
+  // ============================================================================
+  // Deprecated CAP Operations (for backward compatibility)
+  // ============================================================================
+
+  /**
+   * @deprecated Use cache.rt.send() instead. The rt.send() method provides enhanced functionality including read-through metadata, dynamic cache keys, and detailed mode options.
+   */
+  send(arg1: any, service: any, options?: CacheOptions): Promise<any>;
+
+  /**
+   * @deprecated Use cache.rt.run() instead. The rt.run() method provides enhanced functionality including read-through metadata, dynamic cache keys, and detailed mode options.
+   */
+  run(req: any, handler?: Function, options?: CacheOptions): Promise<any>;
+
+  /**
+   * @deprecated Use cache.rt.wrap() instead. The rt.wrap() method provides enhanced functionality including read-through metadata, dynamic cache keys, and detailed mode options.
+   */
+  wrap<T extends (...args: any[]) => Promise<any>>(
+    key: string,
+    asyncFunction: T,
+    options?: CacheOptions
+  ): (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
+
+  /**
+   * @deprecated Use cache.rt.exec() instead. The rt.exec() method provides enhanced functionality including read-through metadata, dynamic cache keys, and detailed mode options.
+   */
+  exec<T>(
+    key: string,
+    asyncFunction: () => Promise<T>,
+    options?: CacheOptions
+  ): Promise<T>;
+
+  // ============================================================================
+  // Tag Resolution
+  // ============================================================================
+
+  /**
+   * Resolve tags for a given query
+   */
+  resolveTags(...args: any[]): Promise<any>;
+
+  // ============================================================================
+  // Statistics and Metrics
+  // ============================================================================
+
+  /**
+   * Get statistics for a specific period
+   */
+  getMetrics(from: Date, to: Date): Promise<CacheStatistics>;
+
+  /**
+   * Get key-specific metrics for a specific period
+   */
+  getKeyMetrics(key: string, from: Date, to: Date): Promise<CacheKeyMetrics>;
+
+  /**
+   * Get current statistics
+   */
+  getCurrentMetrics(): Promise<CacheStatistics>;
+
+  /**
+   * Get current key metrics
+   */
+  getCurrentKeyMetrics(): Promise<CacheKeyMetrics>;
+
+  /**
+   * Clear all metrics
+   */
+  clearMetrics(): Promise<void>;
+
+  /**
+   * Clear key metrics
+   */
+  clearKeyMetrics(): Promise<void>;
+
+  /**
+   * Enable or disable statistics at runtime
+   */
+  setMetricsEnabled(enabled: boolean): Promise<void>;
+
+  /**
+   * Enable or disable key tracking at runtime
+   */
+  setKeyMetricsEnabled(enabled: boolean): Promise<void>;
+
+  /**
+   * Persist metrics to database
+   */
+  persistMetrics(): Promise<void>;
+
+  // ============================================================================
+  // Configuration Management
+  // ============================================================================
+
+  /**
+   * Get current runtime configuration
+   */
+  getRuntimeConfiguration(): Promise<RuntimeConfiguration>;
+
+  /**
+   * Reload runtime configuration from database
+   */
+  reloadRuntimeConfiguration(): Promise<void>;
+
+  /**
+   * Add a cachable function
+   */
+  addCachableFunction(
+    name: string,
+    options: CachableFunctionOptions,
+    isBound?: boolean
+  ): void;
+
+  /**
+   * Dispose of the service
+   */
+  dispose(): Promise<void>;
+
+  // ============================================================================
+  // Private Methods (for internal use)
+  // ============================================================================
+
+  private setupStatisticsHooks(): void;
+  private loadRuntimeConfiguration(): Promise<void>;
+  private getElapsedMs(startTime: [number, number]): number;
+  private _getRaw(key: string | object): Promise<any>;
+}
+
+// ============================================================================
+// Module Export
+// ============================================================================
+
+export default CachingService;