cds-caching 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mike Zaschka
+
+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,322 @@
+# Welcome to cds-caching
+
+## Overview
+
+This plugin for the [SAP Cloud Application Programming Model (CAP)](https://cap.cloud.sap/docs/) provides a robust caching service for CAP applications, addressing common performance challenges in distributed systems.
+
+By reducing database requests and accelerating response times, caching is ideal for handling expensive operations like complex queries/calculations or external API calls. However, it introduces another layer of complexity and should be used with caution.
+
+### Key Features
+
+* **Flexible Key-Value Store** – Store and retrieve data using simple key-based access.
+* **CachingService** – A cds.Service-based implementation with an intuitive API for seamless integration.
+* **Event Handling** – Monitor and react to cache events, such as before/after storage and retrieval.
+* **CAP-specific Caching** – Effortlessly cache CQN queries or CAP cds.Requests using code or the @cache annotation.
+* **TTL Support** – Automatically manage data expiration with configurable time-to-live (TTL) settings.
+* **Tag Support** – Use dynamic tags for flexible cache invalidation options.
+* **Pluggable Storage Options** – Choose between in-memory caching or Redis.
+* **Compression** – Compress cached data to save memory.
+* **Integrated Statistics (WIP)** – Integrated statistics on cache hits, etc.
+### Installation
+
+Installing and using cds-caching is straightforward since it’s a CAP plugin. Simply run:
+
+```
+npm install cds-caching
+```
+
+Next, add a caching service configuration to your package.json. You can even define **multiple caching services**, which is recommended if you need to cache different types of data within your application.
+
+```json
+
+{
+  "cds": {
+    "requires": {
+      "caching": {
+        "impl": "cds-caching",
+        "namespace": "my::app::caching"
+      },
+      "bp-caching": {
+        "impl": "cds-caching",
+        "namespace": "my::app::bp-caching"
+      }
+    }
+  }
+}
+
+```
+### Advanced Configuration
+
+For more control, you can specify additional options. Some of those will be explained later:
+
+```javascript
+
+{
+  "cds": {
+    "requires": {
+      "caching": {
+        "impl": "cds-caching",
+        "namespace": "my::app::caching",
+        "store": "in-memory", // "in-memory" or "redis"
+        "compression": "lz4", // "lz4" or "gzip"
+        "credentials": { // if store is redis
+          "host": "localhost",
+          "port": 6379,
+          "password": "optional",
+        }
+      }
+    }
+  }
+}
+
+```
+### Low level  usage
+
+The **cds-caching** plugin provides direct **key-value storage**, allowing fine-grained caching control. Its API follows a familiar pattern, making it easy to use if you have ever worked with other caching solutions and frameworks.
+Here’s how you can interact with the cache:
+
+```javascript
+// Connect to the caching service
+const cache = await cds.connect.to("caching")
+
+// Store a value
+await cache.set("key", "value")
+
+// Retrieve the value
+await cache.get("key") // => value
+
+// Check if the key exists
+await cache.has("key") // => true/false
+
+// Delete the key
+await cache.delete("key")
+
+// Clear the whole cache
+await cache.clear()
+```
+
+This **low-level API** is useful when you need direct access to cached data, such as storing configuration values, or precomputed results. While the core API is simple, **cds-caching** also provides **higher-level caching strategies** that are more integrated with CAP.  We will look at those in a minute. Before, let's focus on cache events.
+#### Cache Events
+
+The caching service follows the same event-driven principles as cds.Service instances. This means you can hook into events **before** and **after** storing or retrieving data. This is useful for logging, debugging, or performing additional actions when cache operations occur.
+
+Each cache event (event.data.value) contains the following structure:
+* **value** – The cached data.
+* **tags** – Tags assigned to the cached entry.
+* **timestamp** – The timestamp when the cache entry was created. 
+
+Here’s how you can listen for and react to cache events:
+
+```javascript
+
+// Log before the cache is cleared
+cache.before("CLEAR", () => {
+  console.log("Cache is about to be cleared")
+})
+
+// Log before storing data
+cache.before("SET", (event) => {
+  console.log(`Storing key: ${event.data.key} with value: ${event.data.value}`)
+})
+
+// Log after retrieving data
+cache.after("GET", (event) => {
+  console.log(`Retrieved key: ${event.data.key} with value: ${event.data.value}`)
+})
+
+
+```
+
+This approach allows you to monitor cache activity and, if needed, manipulate data before storage or retrieval.
+#### Invalidation via Time-To-Live (TTL)
+
+**cds-caching** supports automatic cache invalidation via **TTL (Time-To-Live)**. Cached values will expire after the specified TTL, preventing stale data from lingering in memory.
+
+```javascript
+// Store a value with a ttl
+await cache.set("key", "value", { ttl: 6000 }) // 60 seconds
+
+// Retrieve the value in time
+await cache.get("key") // => value
+
+await new Promise((resolve) => setTimeout(resolve, 6100)) // wait 61 seonds
+
+// Now the value is not available anymore
+await cache.get("key") // => undefined
+```
+
+TTL-based invalidation is useful for **temporary data, rate-limiting mechanisms, and frequently updated information**. However, **cds-caching** also supports other invalidation strategies, which will be covered in the advanced section.
+#### Compression
+
+To optimize storage, **cds-caching** supports **data compression**. This reduces cache size and can improve performance, especially when caching large datasets. Compression is **applied only when storing data**, meaning applications interact with uncompressed values. Available compression methods include:
+* **lz4** – Faster compression and decompression, ideal for performance-critical applications.
+* **gzip** – Higher compression ratio, reducing storage footprint at the cost of slightly increased CPU usage.
+ 
+Compression can be configured via package.json:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "caching": {
+        "impl": "cds-caching",
+        "compression": "lz4"
+      }
+    }
+  }
+}
+```
+
+### Medium level usage
+
+One of the core principles of **cds-caching** is **seamless integration with CAP**, aligning with CAP’s design and query execution model. As a result, **cds-caching** provides **native support** for **CQN (Core Query Notation) queries** and **cds.Requests**.
+#### Caching CQN queries
+
+CQN queries are widely used in CAP for **database operations** and **remote service calls (e.g., OData requests)**. Since these queries often involve **repeated data retrieval**, caching them can **significantly reduce response times** and **offload system resources**.
+
+**cds-caching** treats **CQN queries as first-class objects**, allowing them to be passed directly into the caching API. Internally, it generates a unique key based on the CQN query structure, ensuring **consistent retrieval** and **cache integrity**.  
+
+**Example: Caching a CQN Query**
+
+```javascript
+
+// Create the CQN object
+const query = SELECT.from(Foo)
+
+// Execute to fetch the result
+const result = await cds.run(query) // => [{...}, {...}]
+
+// Store value in the cache
+await cache.set(query, result) 
+
+// Retrieve the value from the cache using the same CQN object
+const cachedResult = await cache.get(query) // => [{...}, {...}]
+
+// Create the key that is used internally
+const key = cache.createKey(query)
+
+// Delete the value from the cache
+await cache.delete(query)
+
+```
+
+While **CQN queries** can be cached directly, **cds-caching** also supports **caching full** cds.Requests, including their **request context**.  
+#### Caching  cds.Requests
+
+Caching requests is particularly useful when exposing **remote services** through **local CAP services**. For example, if your CAP application proxies an **external API**, caching can significantly reduce redundant requests and improve response times.  
+
+👉 **Use Case:** [Exposing Remote Services](https://cap.cloud.sap/docs/guides/using-services#expose-remote-services)
+
+**cds-caching** automatically includes contextual information in the cache key, making request caching **tenant- and user-aware**. The cache key incorporates:
+
+* req.tenant – Ensures data is scoped per tenant in multi-tenant environments.
+* req.user – Allows user-specific caching when necessary.
+* req.locale – Supports localized responses when caching multilingual content.
+
+**Example: Caching a cds.Request**
+
+```javascript
+this.on('READ', BusinessPartners, async (req, next) => {
+  const bupa = await cds.connect.to('API_BUSINESS_PARTNER')
+  let value = await cache.get(req)
+  if(!value) {
+    value = await bupa.run(req)
+    await cache.set(req, next, { ttl: 3600 })
+  }
+  return value;
+})
+```
+
+**When Not to Cache Full OData Services** 
+
+While caching individual **requests** can improve performance, **caching an entire OData service is generally not recommended**. Here’s why:
+
+1. **Data Inconsistency** – OData services expose **live business data**, which frequently changes. Caching responses without an **appropriate invalidation strategy** can lead to outdated or incorrect data being served.
+
+2. **Complex Query Variations** – OData allows **dynamic query parameters** ($filter, $expand, $orderby, etc.), making it difficult to cache efficiently without storing excessive variations.
+
+3. **Large Payloads** – Full OData responses can be **significantly large**, consuming cache memory inefficiently compared to caching targeted **CQN queries** or specific **request results**.
+
+👉 **Best Practice:** Instead of caching entire OData service responses, cache **specific queries or request results** where the data is frequently accessed and doesn’t change often.
+
+For example, focussing on remote services, **static master data**, or **computed results** is much safer and more efficient than blindly caching full OData responses.
+
+### Read-through CQN queries and cds.Requests
+
+While this API is useful, it follows the **read-aside cache pattern**, meaning **manual cache checks** are required before fetching and storing data. In scenarios where caching logic becomes repetitive, **higher-level caching strategies** can help streamline this process and thanks to the already available CAP API, those are also available in cds-caching.
+
+In **read-through caching**, queries and requests are executed **through the caching service itself**, reducing the need for manual cache handling. **cds-caching** extends CAP’s built-in service methods with two key functions:
+
+* run – Executes **CQN queries** or **requests** against a database or remote OData service.
+[CAP Documentation: srv.run(query)](https://cap.cloud.sap/docs/node.js/core-services#srv-run-query)
+
+* send – Sends **custom synchronous requests** (e.g., to REST APIs) with configurable paths and headers.
+[CAP Documentation: srv.send(request)](https://cap.cloud.sap/docs/node.js/core-services#srv-send-request)
+
+Using **read-through caching**, the previous read-aside pattern can be reduced to a **single line of code**:
+
+```javascript
+this.on('READ', BusinessPartners, async (req, next) => {
+	const bupa = await cds.connect.to('API_BUSINESS_PARTNER')
+	return cache.run(req, bupa, { ttl: 3600 })
+})
+```
+
+With this approach, **all requests to the external service will be automatically executed and cached**, eliminating the need for manual cache handling.
+
+Some other examples :
+
+```javascript
+// Read-through for a CQN query
+const queryResult = await cache.run(SELECT.from("Foo"), db, { ttl: 3600 })
+
+// Read-through for a custom REST request
+const restService = await cds.connect.to({
+  "kind": "rest",
+  "credentials": {
+    "url": "https://services.odata.org/V3/Northwind/Northwind.svc/"
+  }
+});
+const restResult = await cache.send({ method: "GET", path: "Products" }, restService, { ttl: 3600 });
+```
+
+The **read-through strategy** makes caching **cleaner and more maintainable**, as it abstracts cache management entirely. However, **the first request is still slow** (since there’s no cached value yet), but all subsequent requests will be **served instantly from the cache**.
+#### Wrapping async complex code
+
+The **read-through approach** can also be applied to **non-CAP-specific** operations. **cds-caching** provides a wrap function that caches the result of **any asynchronous function**.
+
+```javascript
+const expensiveFunction = async (param) => { /* Do something complex */ }
+
+// Wrap the function with caching
+const cachedExpensiveFunction = await cache.wrap("key", expensiveFunction, { ttl: 3600 }) 
+
+// First call executes the function
+result = await cachedExpensiveFunction("someParam"); // No cache hit
+
+// Subsequent calls retrieve the result from cache
+result = await cachedExpensiveFunction("someParam"); // Cache hit 
+```
+
+This is particularly useful for **heavy computations**, ensuring they only need to be executed **once per TTL period**.
+
+
+## TODO:
+
+- [ ] Add documentation for cache iteration
+- [ ] Add documentation for cache invalidation
+- [ ] Add documentation for cache annotations
+- [ ] Add documentation for cache key generation
+- [ ] Add documentation for cache tags
+- [ ] Add documentation for cache statistics
+- [ ] Add documentation for running locally with redis on docker
+- [ ] Add documentation for running with redis on BTP
+
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for detail

package/cds-plugin.js

@@ -0,0 +1,7 @@
+const cds = require('@sap/cds')
+const CachingService = require('./srv/CachingService')
+const { scanCachingAnnotations } = require('./srv/util')
+
+cds.on('served', scanCachingAnnotations)
+
+module.exports = cds.service.impl(CachingService)

package/index.cds

@@ -0,0 +1,21 @@
+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;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "cds-caching",
+  "version": "0.1.0",
+  "description": "A caching plugin for SAP CAP applications supporting Redis",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mikezaschka/cds-caching.git"
+  },
+  "keywords": [
+    "sap",
+    "cap",
+    "cds",
+    "caching",
+    "redis",
+    "keyv"
+  ],
+  "author": "Mike Zaschka <opensource@mikezaschka.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/mikezaschka/cds-caching/issues"
+  },
+  "homepage": "https://github.com/mikezaschka/cds-caching#readme",
+  "main": "cds-plugin.js",
+  "files": [
+    "srv/**",
+    "index.cds"
+  ],
+  "scripts": {
+    "test": "jest --runInBand --silent",
+    "test:watch": "jest --watch",
+    "lint": "eslint ."
+  },
+  "peerDependencies": {
+    "@sap/cds": ">=8"
+  },
+  "workspaces": [
+    ".",
+    "test/**"
+  ],
+  "dependencies": {
+    "@keyv/compress-gzip": "^2.0.2",
+    "@keyv/compress-lz4": "^1.0.0",
+    "@keyv/redis": "^4.2.0",
+    "keyv": "^5.2.3"
+  },
+  "devDependencies": {
+    "chai": "^4.5.0",
+    "chai-as-promised": "^7.1.2",
+    "chai-subset": "^1.6.0",
+    "eslint": "^8.57.0",
+    "husky": "^9.0.11",
+    "jest": "^29.7.0"
+  },
+  "engines": {
+    "node": ">=16"
+  }
+}

package/srv/CacheStatisticsHandler.js

@@ -0,0 +1,213 @@
+const cds = require('@sap/cds');
+
+class CacheStatisticsHandler {
+    constructor(options = {}) {
+        console.log(options);
+        this.options = {
+            persistenceInterval: 5 * 60 * 60 * 1000, // 5 minutes
+            maxLatencies: 1000,
+            ...options
+        };
+
+        this.stats = {
+            current: {
+                hits: 0,
+                misses: 0,
+                sets: 0,
+                deletes: 0,
+                errors: 0,
+                latencies: []
+            },
+            lastPersisted: Date.now()
+        };
+
+        if (this.options.enabled) {
+            cds.once('served', () => {
+                this.persistInterval = setInterval(
+                    () => this.persistStats(),
+                    this.options.persistenceInterval
+                );
+            })
+            cds.on('shutdown', () => {
+                clearInterval(this.persistInterval)
+            })
+        }
+    }
+
+    recordHit(latencyMs) {
+        this.stats.current.hits++;
+        this.recordLatency(latencyMs);
+    }
+
+    recordMiss() {
+        this.stats.current.misses++;
+    }
+
+    recordSet() {
+        this.stats.current.sets++;
+    }
+
+    recordDelete() {
+        this.stats.current.deletes++;
+    }
+
+    recordError() {
+        this.stats.current.errors++;
+    }
+
+    recordLatency(ms) {
+        this.stats.current.latencies.push(ms);
+        if (this.stats.current.latencies.length > this.options.maxLatencies) {
+            this.stats.current.latencies.shift();
+        }
+    }
+
+    async persistStats() {
+        if (!this.options.enabled) return;
+
+        const now = new Date().toISOString();
+        const hourlyId = `hourly:${now.slice(0, 13)}`;
+        const dailyId = `daily:${now.slice(0, 10)}`;
+
+        const stats = await this.calculateStats();
+
+        try {
+
+            // Persist hourly stats
+            const existingHourly = await SELECT.one.from("cds_caching_Statistics")
+                .where({ ID: hourlyId, cache: this.options.cache });
+
+            if (!existingHourly) {
+                await INSERT.into('cds_caching_Statistics').entries([{
+                    ID: hourlyId,
+                    cache: this.options.cache,
+                    timestamp: now,
+                    period: 'hourly',
+                    ...stats
+                }]);
+            } else {
+                await UPDATE('cds_caching_Statistics')
+                    .set({
+                        hits: { '+=': stats.hits },
+                        misses: { '+=': stats.misses },
+                        sets: { '+=': stats.sets },
+                        deletes: { '+=': stats.deletes },
+                        errors: { '+=': stats.errors },
+                        avgLatency: (existingHourly.avgLatency + stats.avgLatency) / 2,
+                        p95Latency: Math.max(existingHourly.p95Latency, stats.p95Latency),
+                        memoryUsage: stats.memoryUsage,
+                        itemCount: stats.itemCount
+                    })
+                    .where({ ID: hourlyId, cache: this.options.cache });
+            }
+
+            // Update or insert daily stats
+            const existingDaily = await SELECT.one.from("cds_caching_Statistics")
+                .where({ ID: dailyId, cache: this.options.cache });
+
+            if (existingDaily) {
+                await UPDATE('cds_caching_Statistics')
+                    .set({
+                        hits: { '+=': stats.hits },
+                        misses: { '+=': stats.misses },
+                        sets: { '+=': stats.sets },
+                        deletes: { '+=': stats.deletes },
+                        errors: { '+=': stats.errors },
+                        avgLatency: (existingDaily.avgLatency + stats.avgLatency) / 2,
+                        p95Latency: Math.max(existingDaily.p95Latency, stats.p95Latency),
+                        memoryUsage: stats.memoryUsage,
+                        itemCount: stats.itemCount
+                    })
+                    .where({ ID: dailyId, cache: this.options.cache });
+            } else {
+                await INSERT.into("cds_caching_Statistics").entries({
+                    ID: dailyId,
+                    cache: this.options.cache,
+                    timestamp: now,
+                    period: 'daily',
+                    ...stats
+                });
+            }
+
+            this.resetCurrentStats();
+
+        } catch (error) {
+            cds.log('caching').error('Error persisting cache statistics:', error);
+        }
+    }
+
+    async calculateStats() {
+        const latencies = this.stats.current.latencies;
+        const avgLatency = latencies.length > 0
+            ? latencies.reduce((a, b) => a + b, 0) / latencies.length
+            : 0;
+        const p95Latency = latencies.length > 0
+            ? latencies.sort((a, b) => a - b)[Math.floor(latencies.length * 0.95)]
+            : 0;
+
+        return {
+            hits: this.stats.current.hits,
+            misses: this.stats.current.misses,
+            sets: this.stats.current.sets,
+            deletes: this.stats.current.deletes,
+            errors: this.stats.current.errors,
+            avgLatency,
+            p95Latency,
+            memoryUsage: process.memoryUsage().heapUsed,
+            itemCount: await this.options.getItemCount?.() || 0
+        };
+    }
+
+    resetCurrentStats() {
+        this.stats.current = {
+            hits: 0,
+            misses: 0,
+            sets: 0,
+            deletes: 0,
+            errors: 0,
+            latencies: []
+        };
+        this.stats.lastPersisted = Date.now();
+    }
+
+    async getStats(period = 'hourly', from, to) {
+        if (!this.options.enabled) return null;
+
+        const query = SELECT.from("cds_caching_Statistics")
+            .where({ period: period });
+
+        if (from) query.and({ timestamp: { '>=': from } });
+        if (to) query.and({ timestamp: { '<=': to } });
+
+        query.orderBy({ timestamp: 'desc' });
+
+        return await query;
+    }
+
+    async getCurrentStats() {
+        if (!this.options.enabled) return null;
+
+        const { current, lastPersisted } = this.stats;
+        const latencies = current.latencies;
+
+        return {
+            ...current,
+            avgLatency: latencies.length > 0
+                ? latencies.reduce((a, b) => a + b, 0) / latencies.length
+                : 0,
+            p95Latency: latencies.length > 0
+                ? latencies.sort((a, b) => a - b)[Math.floor(latencies.length * 0.95)]
+                : 0,
+            hitRatio: (current.hits / (current.hits + current.misses)) || 0,
+            lastPersisted: new Date(lastPersisted)
+        };
+    }
+
+    dispose() {
+        if (this.persistInterval) {
+            clearInterval(this.persistInterval);
+        }
+    }
+}
+
+module.exports = CacheStatisticsHandler; 

package/srv/CachingService.js

@@ -0,0 +1,528 @@
+const cds = require('@sap/cds');
+const { Keyv } = require('keyv');
+const { default: KeyvRedis } = require('@keyv/redis');
+const { default: KeyvLz4 } = require('@keyv/compress-lz4');
+const { default: KeyvGzip } = require('@keyv/compress-gzip');
+const crypto = require('crypto');
+const CacheStatisticsHandler = require('./CacheStatisticsHandler');
+
+class CachingService extends cds.Service {
+
+    // Store annotated functions with metadata as requests do not contain a target
+    cacheAnnotatedFunctions = {
+        bound: [],
+        unbound: []
+    };
+
+    init() {
+        super.init()
+        this.LOG = cds.log('cds-caching')
+        this.options = this.options || {
+            store: null,
+            compression: null,
+            credentials: {
+            }
+        };
+
+        let cacheOptions = {
+            namespace: this.options.namespace || this.name,
+            ...(this.options.store === "redis" ? { store: new KeyvRedis({
+                ...this.options.credentials,
+                // Redis, Hyperscaler Option on BTP provides a URI
+                ...(this.options.credentials.uri ? { url: this.options.credentials.uri } : {}),
+            }) } : {}),
+            compression: this.options.compression === "lz4" ? new KeyvLz4() : this.options.compression === "gzip" ? new KeyvGzip() : undefined
+        }
+
+        if (this.options.store === "redis") {
+
+            cds.once("shutdown", async () => {
+                if (this.cache.store?.disconnect) {
+                    await this.cache.store.disconnect().catch((err) => {
+                        this.LOG._error && this.LOG.error('Error disconnecting from Redis', err);
+                    });
+                }
+            });
+        }
+
+        this.cache = new Keyv(cacheOptions);
+        this.LOG._info && this.LOG.info(`Caching service initialized with namespace ${cacheOptions.namespace}`);
+
+        this.cache.on('error', err => {
+            this.LOG._error && this.LOG.error('Cache error', err);
+        });
+
+
+        this.on('SET', async (event) => {
+            this.LOG._debug && this.LOG.debug(`SET ${event.data.key}`);
+            if (typeof event.data.value === "object") {
+                event.data.value = JSON.stringify(event.data.value);
+            }
+            await this.cache.set(event.data.key, event.data.value, (event.data.ttl || 0))
+        });
+
+        this.on('GET', async (event) => {
+            const value = await this.cache.get(event.data.key);
+            this.LOG._debug && this.LOG.debug(`GET ${event.data.key}`);
+            if (typeof value === "string") {
+                return JSON.parse(value);
+            }
+            return value;
+        });
+
+        this.on('DELETE', async (event) => {
+            this.LOG._debug && this.LOG.debug(`DELETE ${event.data.key}`);
+            await this.cache.delete(event.data.key);
+        });
+
+        this.on('CLEAR', async (event) => {
+            this.LOG._debug && this.LOG.debug(`CLEAR`);
+            await this.cache.clear();
+        });
+
+        // Initialize statistics if enabled
+        if (this.options.statistics?.enabled) {
+            this.statistics = new CacheStatisticsHandler({
+                enabled: true,
+                ...(this.options.statistics.persistenceInterval ? { persistenceInterval: this.options.statistics.persistenceInterval } : {}),
+                ...(this.options.statistics.maxLatencies ? { maxLatencies: this.options.statistics.maxLatencies } : {}),
+                getItemCount: async () => {
+                    let count = 0;
+                    for await (const _ of this.iterator()) {
+                        count++;
+                    }
+                    return count;
+                }
+            });
+
+            // Enhance methods with statistics
+            this.after('GET', async (result, req) => {
+                const startTime = process.hrtime();
+                try {
+                    if (result === undefined) {
+                        this.statistics.recordMiss();
+                    } else {
+                        this.statistics.recordHit(this.getElapsedMs(startTime));
+                    }
+                } catch (error) {
+                    this.statistics.recordError();
+                    throw error;
+                }
+            });
+
+            this.after('SET', () => this.statistics.recordSet());
+            this.after('DELETE', () => this.statistics.recordDelete());
+        }
+    }
+
+    addCachableFunction(name, options, isBound = false) {
+
+        this.cacheAnnotatedFunctions[isBound ? 'bound' : 'unbound'].push({ name, options });
+    }
+
+    getElapsedMs(startTime) {
+        const [seconds, nanoseconds] = process.hrtime(startTime);
+        return seconds * 1000 + nanoseconds / 1000000;
+    }
+
+    async getStats(period, from, to) {
+        return this.statistics?.getStats(period, from, to);
+    }
+
+    async getCurrentStats() {
+        return this.statistics?.getCurrentStats();
+    }
+
+    async dispose() {
+        this.statistics?.dispose();
+        await super.dispose();
+    }
+
+    /**
+     * Overloaded send method that caches the response of a remote service.
+     * 
+     * @returns {Promise<any>} - the result
+     */
+    async send() {
+        const arg1 = arguments[0];
+        const service = arguments[1];
+        const options = {
+            ttl: 0,
+            ...(arguments[2] || {}),
+        }
+
+        if (typeof arg1 !== "object" || !service.send || typeof options !== "object" || arg1.method !== "GET") {
+            return super.send(...arguments);
+        }
+
+        const key = this.createKey(arg1, options.key);
+
+        if (await this.has(key)) {
+            return this.get(key);
+        }
+        const response = await service.send(arg1);
+        await this.set(key, response, options);
+        return response;
+    }
+
+    // Function to extract the cache options from the request
+    extractFunctionCacheOptions(req, options) {
+        const functionType = req.query ? 'bound' : 'unbound';
+        const functionOptions = this.cacheAnnotatedFunctions[functionType].find(f => f.name === req.event);
+
+        return {
+            ttl: functionOptions?.['@cache.ttl'] || 0,
+            key: functionOptions?.['@cache.key'] || { template: '{tenant}-{user}-{locale}-{hash}' },
+            tags: functionOptions?.['@cache.tags'] || [],
+            ...(options || {}),
+        }
+    }
+
+    extractEntityCacheOptions(req, options) {
+        return {
+            ttl: req.target?.['@cache.ttl'] || 0,
+            key: req.target?.['@cache.key'] || { template: '{tenant}-{user}-{locale}-{hash}' },
+            tags: req.target?.['@cache.tags'] || [],
+            ...(options || {}),
+        }
+    }
+
+    /**
+     * Overloaded run method that caches multiple things magically in the background
+     * 
+     * @param {cds.ql} query - the query to run
+     * @param {Service} service - service instance to run the query on
+     * @param {object} options - additional options
+     * 
+     * 
+     * @param {Request} request - the request to run
+     * @param {next} function - the next fuction
+     * @param {object} options - additional options
+
+     * @returns {Promise<any>} - the result
+     */
+
+    async run() {
+        const arg1 = arguments[0];
+        if (typeof arg1 === "object") {
+            switch (arg1.constructor.name) {
+                case "Request":
+                case "NoaRequest":
+                    const req = arg1;
+                    const next = arguments[1];
+
+                    if (req.query?.UPDATE || req.query?.INSERT || req.query?.DELETE) {
+                        return next();
+                    }
+
+                    req.cacheOptions = req.event ? this.extractFunctionCacheOptions(req, arguments[2]) : this.extractEntityCacheOptions(req, arguments[2]);
+                    req.cacheKey = this.createKey(req, req.cacheOptions.key);
+                    req.res?.setHeader('x-sap-cap-cache-key', req.cacheKey);
+                    if (await this.has(req.cacheKey)) {
+                        return this.get(req.cacheKey);
+                    }
+                    const response = await next();
+                    req.cacheOptions.tags = this.resolveTags(req.cacheOptions.tags, response, req.params);
+                    await this.set(req.cacheKey, response, req.cacheOptions);
+                    return response;
+                case "cds.ql":
+                    const query = arg1;
+                    const srv = arguments[1];
+
+                    if (query.SELECT) {
+                        
+                        let options = {
+                            ttl: 0,
+                            tags: [],
+                            key: { template: '{hash}' },
+                            ...(arguments[2] || {}),
+                        };
+                        query.cacheKey = this.createKey(query, options.key);
+                        if (await this.has(query.cacheKey)) {
+                            return this.get(query.cacheKey);
+                        }
+                        const data = await srv.run(query);
+                        options.tags = this.resolveTags(options.tags, data, query.params);
+                        await this.set(query.cacheKey, data, options);
+                        return data;
+                    } else {
+                        return srv.run(query);
+                    }
+
+            }
+        }
+        return super.run(arg1);
+    }
+
+    /**
+     * Wraps an async function and caches the result
+     * 
+     * @param {string} key - the key to cache
+     * @param {function} asyncFunction - the async function to cache
+     * @param {object} options - additional options
+     * @returns {function} - the wrapped function
+     */
+    wrap(key, asyncFunction, options = {}) {
+        const cacheKey = this.createKey(key, options.key);
+        return async (...args) => {
+            if (await this.has(cacheKey)) {
+                return this.get(cacheKey);
+            }
+            const response = await asyncFunction(...args);
+            await this.set(cacheKey, response, options);
+            return response;
+        }
+    }
+
+    async set(key, value, options = {}) {
+        const wrappedValue = {
+            value,
+            tags: options.tags || [],
+            timestamp: Date.now()
+        };
+        await this.send('SET', {
+            key: this.createKey(key, options.key),
+            value: wrappedValue,
+            ttl: options.ttl || 0
+        });
+    }
+
+    async get(key) {
+        const wrappedValue = await this.send('GET', { key: this.createKey(key) });
+        return wrappedValue?.value;
+    }
+
+    async has(key) {
+        return this.cache.has(this.createKey(key));
+    }
+
+    async delete(key) {
+        await this.send('DELETE', { key: this.createKey(key) });
+    }
+
+    async clear() {
+        await this.send('CLEAR');
+    }
+
+
+    async deleteByTag(tag) {
+        for await (const [key, wrappedValue] of this.iterator()) {
+            if (wrappedValue?.tags?.includes(tag)) {
+                await this.delete(key);
+            }
+        }
+    }
+
+    // Metadata
+    async metadata(key) {
+        const wrappedValue = await this.send('GET', { key: this.createKey(key) });
+        if (!wrappedValue) return null;
+
+        const { value, ...metadata } = wrappedValue;
+        return metadata;
+    }
+
+    async tags(key) {
+        const wrappedValue = await this.send('GET', { key: this.createKey(key) });
+        return wrappedValue?.tags || [];
+    }
+
+    // Iterators
+    async *iterator() {
+        for await (const [key, value] of this.cache.iterator()) {
+            if (typeof value === "string") {    
+                yield [key, JSON.parse(value)];
+            } else {
+                yield [key, value];
+            }
+        }
+    }
+
+    /**
+     * Resolves tags from tag configurations and data
+     * @param {Array} tagConfigs - Array of tag configuration objects
+     * @param {Object|Array} data - Data object(s) to extract data values from
+     * @param {Object} params - Parameters object to extract values from
+     * @returns {string[]} Array of resolved tags
+     */
+    resolveTags(tagConfigs = [], data, params = {}) {
+        let resolvedTags = [];
+
+        // Handle no data/params case
+        if (!data && !params) {
+            // Only process static tags when no sources are present
+            return tagConfigs
+                .filter(config => config.value)
+                .map(config => config.value);
+        }
+
+        // Convert data to array if single object
+        const dataArray = data ? (Array.isArray(data) ? data : [data]) : [];
+
+        // Process each tag configuration
+        tagConfigs.forEach(config => {
+            if (config.value) {
+                // Static tag
+                resolvedTags.push(config.value);
+            } else if (config.data) {
+                // Dynamic tags from data
+                dataArray.forEach(item => {
+                    if (typeof config.data === "string") {
+                        // Single data configuration
+                        const dataValue = item[config.data];
+                        if (dataValue) {
+                            const tag = [
+                                config.prefix,
+                                dataValue,
+                                config.suffix
+                            ].filter(Boolean).join('');
+                            resolvedTags.push(tag);
+                        }
+                    } else if (Array.isArray(config.data)) {
+                        // Multiple data configuration
+                        const dataValues = config.data
+                            .map(data => item[data])
+                            .filter(Boolean);
+
+                        if (dataValues.length > 0) {
+                            const combinedValue = dataValues.join(config.separator || ':');
+                            const tag = [
+                                config.prefix,
+                                combinedValue,
+                                config.suffix
+                            ].filter(Boolean).join('');
+                            resolvedTags.push(tag);
+                        }
+                    }
+                });
+            } else if (config.param) {
+                // Dynamic tags from params
+                if (typeof config.param === "string") {
+                    // Single param configuration
+                    const paramValue = params[config.param];
+                    if (paramValue) {
+                        const tag = [
+                            config.prefix,
+                            paramValue,
+                            config.suffix
+                        ].filter(Boolean).join('');
+                        resolvedTags.push(tag);
+                    }
+                } else if (Array.isArray(config.param)) {
+                    // Multiple params configuration
+                    const paramValues = config.param
+                        .map(param => params[param])
+                        .filter(Boolean);
+
+                    if (paramValues.length > 0) {
+                        const combinedValue = paramValues.join(config.separator || ':');
+                        const tag = [
+                            config.prefix,
+                            combinedValue,
+                            config.suffix
+                        ].filter(Boolean).join('');
+                        resolvedTags.push(tag);
+                    }
+                }
+            }
+        });
+
+        // Remove duplicates
+        return [...new Set(resolvedTags)];
+    }
+
+    // Basic cache operations
+    createKey(keyOrObject, options = {}) {
+
+        // If the key is a string, use it
+        if (typeof keyOrObject === "string") {
+            return keyOrObject;
+        }
+
+        // Otherwise, create a key based on the object
+        if (typeof keyOrObject === "object") {
+
+            // If the key is provided in the options, use it
+            if (keyOrObject.cacheKey) {
+                return keyOrObject.cacheKey;
+            }
+
+            switch (keyOrObject.constructor.name) {
+                case "Request":
+                case "NoaRequest":
+
+                    return this.createCacheKey((!options.value && !options.template) ? { template: '{tenant}:{user}:{locale}:{hash}' } : options, { 
+                        req: keyOrObject, 
+                        params: keyOrObject.params, 
+                        data: keyOrObject.data, 
+                        locale: keyOrObject.locale, 
+                        user: keyOrObject.user.id, 
+                        tenant: keyOrObject.tenant 
+                    });
+                case "cds.ql":
+                    if (keyOrObject.SELECT) {
+                        return this.createCacheKey((!options.value && !options.template) ? { template: '{hash}' } : options, { query: keyOrObject });
+                    } else {
+                        return undefined;
+                    }
+                default:
+                    return this.createCacheKey((!options.value && !options.template) ? { template: '{hash}' } : options, { data: keyOrObject });
+            }
+        }
+    }
+
+    /**
+     * Creates a cache key based on configuration and context
+     * @param {Object} keyConfig - Key configuration object
+     * @param {Object} context - Context containing data, params, and request info
+     * @returns {string} Generated cache key
+     */
+    createCacheKey(keyConfig = {}, context = {}) {
+        const { data, params, req, query, locale, user, tenant } = context;
+
+        // If a static key value is provided, use it
+        if (keyConfig.value) {
+            return keyConfig.value;
+        }
+
+        let keyValue = '';
+
+        const hashParts = [
+            ...(data ? [data] : []),
+            ...(params ? [params] : []),
+            ...(query ? [query] : [])
+        ];
+
+        const createHash = (data) => crypto.createHash('md5').update(JSON.stringify(data)).digest('hex');
+
+        // Handle template with placeholders
+        if (keyConfig.template) {
+            const contextVars = {
+                tenant: tenant || 'global',
+                user: user || 'anonymous',
+                locale: locale || 'en',
+                hash: createHash(hashParts)
+            };
+
+            keyValue = keyConfig.template.replace(
+                /\{(tenant|user|locale|hash)\}/g,
+                (match, variable) => contextVars[variable]
+            );
+        }
+
+        // If no key value generated, create hash from input
+        if (!keyValue) {
+            keyValue = createHash(hashParts);
+        }
+
+        // Combine with prefix/suffix
+        return [
+            keyConfig.prefix,
+            keyValue,
+            keyConfig.suffix
+        ].filter(Boolean).join('');
+    }
+
+}
+
+module.exports = CachingService;

package/srv/statistics-service.cds

@@ -0,0 +1,37 @@
+using {cds_caching as stats} from '../index.cds';
+
+@path    : 'cache-stats'
+//@requires: 'cache-admin'
+service StatisticsService {
+    @readonly
+    entity Statistics as projection on stats.Statistics;
+
+/*
+    @readonly
+    @cds.persistence.skip
+    entity CurrentStats {
+        key ID        : String default 'current';
+        key cache     : String;
+            hits      : Integer default 0;
+            misses    : Integer default 0;
+            sets      : Integer default 0;
+            deletes   : Integer default 0;
+            errors    : Integer default 0;
+            latencies : array of Double; // Rolling window of recent latencies
+    }
+
+    // Action to get stats for a specific time range
+    function getStats(period : String enum {
+        hourly;
+        daily;
+        monthly;
+    },
+                      from : DateTime,
+                      to : DateTime) returns array of Statistics;
+
+    // Action to get current statistics
+    function getCurrentStats()       returns CurrentStats;
+    // Action to manually trigger stats persistence
+    action   persistStats()          returns Boolean;
+*/
+}

package/srv/statistics-service.js

@@ -0,0 +1,72 @@
+const cds = require('@sap/cds')
+
+class StatisticsService extends cds.ApplicationService {
+    async init() {
+        const { Statistics, Current } = this.entities
+
+        // Get reference to cache service
+        const cache = await cds.connect.to('caching')
+        
+        // Handle getStats function
+        this.on('getStats', async (req) => {
+            const { period, from, to } = req.data
+            return cache.getStats(period, from, to)
+        })
+
+        // Handle getCurrentStats function
+        this.on('getCurrentStats', async () => {
+            const stats = await cache.getCurrentStats()
+            if (!stats) return null
+
+            // Convert to CurrentStats entity format
+            return {
+                id: 'current',
+                hits: stats.hits,
+                misses: stats.misses,
+                sets: stats.sets,
+                deletes: stats.deletes,
+                errors: stats.errors,
+                latencies: stats.latencies
+            }
+        })
+
+        // Handle persistStats action
+        this.on('persistStats', async (req) => {
+            if (!cache.statistics?.persistStats) {
+                req.warn('Statistics are not enabled')
+                return false
+            }
+
+            await cache.statistics.persistStats()
+            return true
+        })
+
+        // Add custom handlers for the entities if needed
+        this.before('READ', 'Statistics', req => {
+            if (!cache.statistics) {
+                req.warn('Statistics are not enabled')
+                return []
+            }
+        })
+
+        this.on('READ', 'CurrentStats', async req => {
+            const stats = await cache.getCurrentStats()
+            if (!stats) return []
+
+            // Convert to CurrentStats entity format
+            return {
+                id: 'current',
+                hits: stats.hits,
+                misses: stats.misses,
+                sets: stats.sets,
+                deletes: stats.deletes,
+                errors: stats.errors,
+                latencies: stats.latencies
+            }
+        })
+
+        await super.init()
+    }
+}
+
+module.exports = StatisticsService 

package/srv/util.js

@@ -0,0 +1,83 @@
+const cds = require("@sap/cds")
+
+const bindFunction = async (service, action, isBound = false) => {
+    const cache = await cds.connect.to(action['@cache.service'] || "caching");
+    cache.addCachableFunction(action.name.split('.').pop(), action, isBound);
+
+    service.prepend(function () {
+        service.on(action.name.split('.').pop(), async (req, next) => {
+            const cache = await cds.connect.to(action['@cache.service'] || "caching");
+            const data = await cache.run(req, next, { 
+                ttl: action['@cache.ttl'], 
+                tags: action['@cache.tags'],
+                key: action['@cache.key']
+            });
+            return data;
+        })
+    })
+}
+
+const bindEntity = async (service, entity) => {
+    service.prepend(function () {
+        service.on('READ', entity.name, async (req, next) => {
+            const cache = await cds.connect.to(entity['@cache.service'] || "caching");
+            const data = await cache.run(req, next, {
+                ttl: entity['@cache.ttl'], 
+                tags: entity['@cache.tags'],
+                key: entity['@cache.key']
+            });
+            return data;
+        })
+    })
+}
+
+const scanCachingAnnotations = async (srvs) => {
+    LOG = cds.log('cds-caching')
+
+    // Grep all app services
+    const services = [];
+    for (const [name, config] of Object.entries(srvs)) {
+        const service = await cds.connect.to(name);
+
+        if (service.definition?.kind === 'service') {
+            services.push(service);
+        }
+    }
+
+    // Grep all external services
+    for (const [name, config] of Object.entries(cds.env.requires)) {
+        if (config.kind === 'odata-v2' || config.kind === 'odata' || config.kind === 'rest') {
+            const service = await cds.connect.to(name);
+            services.push(service);
+        }
+    }
+
+    for (const service of services) {
+
+        // functions
+        for (const [name, action] of Object.entries(service.actions)) {
+            if (Object.keys(action).some(key => key.startsWith('@cache')) && action.kind === 'function') {
+                LOG._debug && LOG.debug(`Caching enabled for function ${action.name}`);
+                await bindFunction(service, action);
+            }
+        }
+
+        // entities
+        for (const entity of service.entities) {
+            if (Object.keys(entity).some(key => key.startsWith('@cache'))) {
+                await bindEntity(service, entity);
+                LOG._debug && LOG.debug(`Caching enabled for entity ${entity.name}`);
+            }
+
+            // bound functions
+            for (const [name, action] of Object.entries(entity.actions || {})) {
+                if (Object.keys(action).some(key => key.startsWith('@cache')) && action.kind === 'function') {
+                    bindFunction(service, action, true);
+                    LOG._debug && LOG.debug(`Caching enabled for bound function ${action.name}`);
+                }
+            }
+        }
+    }
+}
+
+module.exports = { scanCachingAnnotations }