cds-caching 0.2.0 → 0.3.0

package/README.md

@@ -26,12 +26,12 @@ cds-caching is specifically designed for efficient caching, not data replication
 ### Key Features
 
 * **Flexible Key-Value Store** – Store and retrieve data using simple key-based access.
-* **CachingService** – A CALESI-compliant cds.Service implementation with an intuitive API for seamless integration.
+* **CachingService** – A cds.Service implementation with an intuitive API for seamless integration into CAP.
 * **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.
+* **Pluggable Storage Options** – Choose between in-memory caching, SQLite or Redis.
 * **Compression** – Compress cached data to save memory using LZ4 or GZIP.
 * **Integrated Statistics** – Monitor cache performance with hit rates, latencies, and more.
 
@@ -74,13 +74,20 @@ For more control, you can specify additional options:
       "caching": {
         "impl": "cds-caching",
         "namespace": "my::app::caching",
-        "store": "in-memory", // "in-memory" or "redis"
+        "store": "in-memory", // "in-memory" or "sqlite" or "redis"
         "compression": "lz4", // "lz4" or "gzip"
-        "credentials": { // if store is redis
+        "credentials": { // if store is redis or sqlite
+
+          // Redis specific
           "host": "localhost",
           "port": 6379,
           "password": "optional",
           "url": "redis://..." // Alternative: Redis connection URI
+
+          // SQLite specific
+          "url": "sqlite://./cache.sqlite"
+          "table": "cache",
+          "busyTimeout": 10000
         },
         "statistics": {
           "enabled": true,
@@ -93,6 +100,104 @@ For more control, you can specify additional options:
 }
 ```
 
+### Real-World Usage and Deployment
+
+
+#### Storage Options
+
+cds-caching provides 3 storage options:
+
+##### In-Memory Cache (for development / small-scale uses)
+- Simple and fast, but not persistent
+- Not suitable for production since Node.js runtime memory is limited
+- Data is lost when the application restarts
+- Memory on SAP BTP Cloud Foundry is limited (up to 16 GB) and produces costs
+
+##### SQLite (for medium-size use uses)
+- Data is stored in local SQLite database
+- Data is persited next to SAP BTP application with disk-quota up to 10 GB
+- Cache will be removed after each deployment to SAP BTP
+- No distributed cache between application instances (horizontal scaling)
+
+##### Redis Cache (recommended for production)
+- Persistent and supports distributed caching
+- Works across multiple app instances, making it ideal for scalable applications
+- Available on SAP BTP via hyperscaler options (e.g., AWS, Azure, Google Cloud)
+- Even trial accounts provide Redis access
+
+#### Redis Development Setup
+
+##### Running Redis Locally via Docker
+For local development, Redis can be quickly set up using Docker. A simple docker-compose configuration provides a lightweight caching environment:
+
+1. Create a `docker-compose.yml` file:
+```yaml
+services:
+  redis:
+    image: redis:latest
+    container_name: local-redis
+    ports:
+      - "6379:6379"
+```
+
+2. Run Redis with: 
+```bash
+docker compose up -d
+```
+
+3. Modify the `package.json` configuration to connect to the local Redis instance:
+```json
+{
+  "cds": {
+    "requires": {
+      "caching": {
+        "impl": "cds-caching",
+        "namespace": "myCache",
+        "store": "redis",
+        "[development]": {
+          "credentials": {
+            "host": "localhost",
+            "port": 6379
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Now, caching will be handled by Redis instead of in-memory storage during development.
+
+#### Production Deployment on SAP BTP
+
+![Redis on SAP BTP](./docs/caching-btp.png)
+
+For production deployments on SAP BTP, Redis can be provisioned as a managed service through the Redis on SAP BTP hyperscaler option. An instance can be provisioned via trial or even as a Free Tier to explore the service. However, for production scenarios the size of the Redis instance should match your caching requirements.
+
+To bind Redis to your CAP application on SAP BTP, add the following configuration in `mta.yaml`. This will automatically create the service instance and bind your application to it. Since the credentials will automatically be fetched by CAP, make sure to maintain the service-tags to match the kind property of your cds-caching service(s) in the package.json:
+
+```yaml
+modules:
+  - name: cap-app-srv
+    # ... other module configuration ...
+    requires:
+      - name: redis-cache
+
+resources:
+  - name: redis-cache
+    type: org.cloudfoundry.managed-service
+    parameters:
+      service: redis-cache
+      service-plan: trial
+      service-tags:
+        # Must match the kind property in the package.json
+        - cds-caching
+```
+
+> 👉 **Tip**: There is a detailed [blog series on Redis in SAP BTP](https://community.sap.com/t5/technology-blogs-by-sap/redis-on-sap-btp-understanding-service-entitlements-and-metrics/ba-p/13738371) explaining how to set up Redis and connect via SSH for local/hybrid testing, as this is by default not possible.
+
+
+
 ### Usage Patterns
 
 The caching service provides a flexible API for caching data in CAP applications. Here are the key usage patterns:
@@ -146,11 +251,12 @@ const result = await cache.run(query, db)
 
 This will transparently cache the result of the query and return the cached result if available for all further requests.
 
-#### 3. Request-Level Caching
+#### 3. RemoteService Request-Level Caching
 
-Cache entire CAP requests with context awareness (e.g. user, tenant, locale, etc.), which is useful for caching slow remote service calls. The caching service will automatically generate a key for the request based on the request object and the current user, tenant and locale.
+Cache entire CAP requests with context awareness (e.g. user, tenant, locale, etc.), which is useful for caching slow remote service calls or even application services. The caching service will automatically generate a key for the request based on the request object and the current user, tenant and locale.
 
 ```javascript
+// Cache the requests to an exposed external entity
 this.on('READ', BusinessPartners, async (req, next) => {
   const bupa = await cds.connect.to('API_BUSINESS_PARTNER')
   let value = await cache.get(req)
@@ -165,17 +271,45 @@ this.on('READ', BusinessPartners, async (req, next) => {
 Alternatively use read-through caching via the `run` method to let the caching service handle the caching transparently:
 
 ```javascript
-const bupa = await cds.connect.to('API_BUSINESS_PARTNER')
-const result = await cache.run(req, bupa)
+this.on('READ', BusinessPartners, async (req, next) => {
+  const bupa = await cds.connect.to('API_BUSINESS_PARTNER')
+  return await cache.run(req, bupa)
+})
+
 ```
 
 This will transparently cache the result of the request and return the cached result if available for all further requests.
 
-#### 4. Declarative Caching with Annotations
+### 4. ApplicationService Request-Level Caching
+
+
+> Caching an entire entity should be used with caution, as it will cache all permutations of requests ($filter, $expand, $orderby, etc.) on the entity, which will lead to a huge number of cache entries. Use this only for entities where you can guarantee a low number of different queries.
+
 
-Use annotations to enable caching on service entities or OData functions. The caching service will automatically generate a key for the request based on the request object and the current user, tenant and locale. 
+But not only external services can be cached, it's also possible to cache requests against an ApplicationService.
+Here, you should make use of the [`prepend`](https://cap.cloud.sap/docs/node.js/core-services#srv-prepend) function, to register the `on` handler before the default handler. Thus, it is possible to first check for the cache entries and only execute the default behavior if necessary.
 
-**Caching an entire entity should be used with caution, as it will cache all permutations of requests ($filter, $expand, $orderby, etc.) on the entity, which will lead to a huge number of cache entries. Use this only for entities where you can guarantee a low number of different queries.**
+
+```javascript
+class MyService extends cds.ApplicationService {
+  async init() {
+
+    // Read-through caching for the full entity
+    this.prepend(() => {
+      const { MyEntity } = this.entities;
+      this.on('READ', MyEntity, async (req, next) => {
+        const cache = cds.connect.to("caching");
+        return cache.run(req, next);
+      });
+    });
+    return super.init()
+  }
+}
+```
+
+#### 5. ApplicationService Request-Level Caching with Annotations
+
+Alternatively to doing this via code, you can use annotations to enable caching on service entities or OData functions. The caching service will automatically generate a key for the request based on the request object and the current user, tenant and locale. 
 
 ```
 service MyService {
@@ -266,7 +400,49 @@ const result = await cache.exec("key", async () => {
 })
 ```
 
-#### 2. Tag-Based
+#### 2. Key-Based
+
+Key-based invalidation is a way to invalidate cache entries based on a specific key.
+
+```javascript
+await cache.delete("key")
+```
+
+Keys are critical for cache invalidation. To allow custom key management, you can override the auto-generated key. This option is available for all essential methods (e.g cache.set, cache.run, cache.send, cache.createKey) and for the annotations.
+ 
+```javascript
+// No key override given, string will just be used as keys
+await cache.set('key', 'value') // key: key 
+
+// No key override given, objects will be smartly hashed 
+await cache.set(SELECT.from(Foo)) // key: bd3f3690d3e96a569bd89d9e207a89af
+
+// Automatically build the key for retrieval/deletion
+cache.createKey(SELECT.from(Foo)) // key: bd3f3690d3e96a569bd89d9e207a89af
+
+// Override and use your own key based on a fixed value
+await cache.set(SELECT.from(Foo, 1), { key: { value: "foo:1" } })
+
+// Override and only for requests, use request context information
+await cache.run(req, remoteService, { key: { template: "mykey:{tenant}:{user}:{locale}:{hash}" } })
+
+// This requests will be cached for all users and for each locale 
+await cache.set(req, remoteService, { key: { template: "mykey:{user}:{locale}:{hash}" } })
+```
+
+Overriding keys support the following configuration options:
+- `value` – generates a static value
+- `prefix` – will add this piece at the beginning
+- `suffix` - will ad this piece at the end
+- `template` - will set a value filled with placeholders, available placeholders are (only relevant for cds.Requests):
+  - `{user}`: The current user
+  - `{tenant}`: The current tenant
+  - `{locale}`: The current locale
+  - `{hash}`: The hash of the request query/params/data/path/etc.
+
+With well-structured keys, invalidating cache entries becomes a lot easier. However, for more complex scenarios tags provide an even more effective solution, as tags can automatically be created based on the cached data.
+
+#### 3. Tag-Based
 
 Tags are a way to invalidate cache entries based on a specific tag. Tags need to be provided explicitly when storing a value in the cache and are supported for all cache methods (e.g. `set`, `run`, `send`, `wrap`, `exec`).
 Tags can be provided as an array of strings or as an array of objects with the following properties:
@@ -434,7 +610,8 @@ The following properties are accepted:
 | Property      | Description   | Example  |
 | ------------- | ------------- | ----------
 | ttl           | Time-to-live in milliseconds. | `1000`
-| tags          | Array of tags to associate with the value. Tags can be dynamic based on the given value (see chapter Cache Invalidation Strategies) | `[{template: 'user-{user}', value: '123'}]`
+| key           | Key override for the cache for full control over the key management (see chapter Cache Invalidation Strategies) | `{template: 'user-{user}', value: '123'}`
+| tags          | Array of tags to associate with the value. Tags can be dynamic based on the stored cache data (see chapter Cache Invalidation Strategies) | `[{template: 'user-{user}', value: '123'}]`
 
 ---
 
@@ -572,7 +749,7 @@ The result of the function.
 
 --- 
 
-### `await cache.iterator()`
+### `await cache.iterator() : AsyncIterator<{ key: string, value: { value: any, tags: string[], timestamp: number } }>`
 
 Returns an iterator over all cache entries.
 
@@ -582,6 +759,36 @@ An iterator over all cache entries.
 
 ---
 
+### `await cache.tags(key: any) : string[]`
+
+Returns the tags for a given key.
+
+#### `key: any`
+
+The key to get the tags for. The key handling is the same as for the `createKey` method.
+
+#### Returns
+
+An array of tags. If the key does not exist, an empty array is returned.
+
+---   
+
+### `await cache.metadata(key: any) : { tags: string[], timestamp: number } | undefined`
+
+Returns the metadata for a given key.
+
+#### `key: any`
+
+The key to get the metadata for. The key handling is the same as for the `createKey` method.
+
+#### Returns
+
+An object containing the metadata for the given key or `undefined` if the key does not exist. The metadata object contains the following properties:
+
+- `tags`: An array of tags.
+- `timestamp`: The timestamp of the cache entry.  
+
+---
 
 ### Contributing
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cds-caching",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "A caching plugin for SAP CAP applications supporting Redis",
   "repository": {
     "type": "git",
@@ -41,17 +41,16 @@
   "dependencies": {
     "@keyv/compress-gzip": "^2.0.2",
     "@keyv/compress-lz4": "^1.0.0",
-    "@keyv/redis": "^4.2.0",
-    "keyv": "^5.2.3"
+    "@keyv/redis": "^4.3.1",
+    "@keyv/sqlite": "^4.0.1",
+    "keyv": "^5.3.1"
   },
   "devDependencies": {
-    "chai": "^4.5.0",
-    "chai-as-promised": "^7.1.2",
-    "chai-subset": "^1.6.0",
-    "eslint": "^8.57.0",
-    "husky": "^9.0.11",
+    "eslint": "^9.21.0",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
-    "release-it": "^18.1.2"
+    "release-it": "^18.1.2",
+    "@cap-js/cds-test": "^0.2.0"
   },
   "engines": {
     "node": ">=16"

package/srv/CachingService.js

@@ -1,6 +1,7 @@
 const cds = require('@sap/cds');
 const { Keyv } = require('keyv');
 const { default: KeyvRedis } = require('@keyv/redis');
+const { default: KeyvSqlite } = require('@keyv/sqlite');
 const { default: KeyvLz4 } = require('@keyv/compress-lz4');
 const { default: KeyvGzip } = require('@keyv/compress-gzip');
 const crypto = require('crypto');
@@ -20,30 +21,45 @@ class CachingService extends cds.Service {
         this.options = this.options || {
             store: null,
             compression: null,
-            credentials: {
-            }
+            credentials: { }
         };
 
+        let store;
+
+        switch (this.options.store) {
+            case "sqlite":
+                store = new KeyvSqlite({
+                    url: this.options.credentials?.url,
+                    table: this.options.credentials?.table || 'cache',
+                    busyTimeout: this.options.credentials?.busyTimeout || 10000
+                });
+                break;
+            case "redis":
+                store = new KeyvRedis({
+                    ...this.options.credentials,
+                    // Redis, Hyperscaler Option on BTP provides a URI
+                    ...(this.options.credentials?.uri ? { url: this.options.credentials?.uri } : {}),
+                });
+
+                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);
+                        });
+                    }
+                });
+                break;
+            default:
+                store = new Map();
+                break;
+        }
+
         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 } : {}),
-            }) } : {}),
+            store: store,
             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}`);
@@ -218,8 +234,9 @@ class CachingService extends cds.Service {
                     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 cachedValue = await this.get(req.cacheKey);
+                    if (cachedValue) {
+                        return cachedValue;
                     }
                     const response = await next();
                     req.cacheOptions.tags = this.resolveTags(req.cacheOptions.tags, response, req.params);
@@ -230,7 +247,7 @@ class CachingService extends cds.Service {
                     const srv = arguments[1];
 
                     if (query.SELECT) {
-                        
+
                         let options = {
                             ttl: 0,
                             tags: [],
@@ -277,7 +294,7 @@ class CachingService extends cds.Service {
     async set(key, value, options = {}) {
         const wrappedValue = {
             value,
-            tags: options.tags || [],
+            tags: this.resolveTags(options.tags, value, options.params) || [],
             timestamp: Date.now()
         };
         await this.send('SET', {
@@ -330,7 +347,7 @@ class CachingService extends cds.Service {
     // Iterators
     async *iterator() {
         for await (const [key, value] of this.cache.iterator()) {
-            if (typeof value === "string") {    
+            if (typeof value === "string") {
                 yield [key, JSON.parse(value)];
             } else {
                 yield [key, value];
@@ -346,85 +363,77 @@ class CachingService extends cds.Service {
      * @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);
-        }
+        // Handle empty/invalid configs
+        if (!tagConfigs?.length) return [];
 
-        // Convert data to array if single object
-        const dataArray = data ? (Array.isArray(data) ? data : [data]) : [];
+        // Convert data to array if single object or string
+        const dataArray = !data ? [] :
+            Array.isArray(data) ? data :
+                typeof data === 'string' ? [data] : [data];
 
         // Process each tag configuration
-        tagConfigs.forEach(config => {
+        const resolvedTags = tagConfigs.flatMap(config => {
+            // Handle string tags
+            if (typeof config === 'string') {
+                return [config];
+            }
+
+            // Handle invalid/empty config objects
+            if (!config || typeof config !== 'object') {
+                return [];
+            }
+
+            // Handle static value tags
             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])
+                const tag = [
+                    config.prefix,
+                    config.value,
+                    config.suffix
+                ].filter(Boolean).join('');
+                return [tag];
+            }
+
+            // Handle data-based tags
+            if (config.data && dataArray.length) {
+                return dataArray.flatMap(item => {
+                    if (typeof item !== 'object') return [];
+
+                    const dataFields = Array.isArray(config.data) ? config.data : [config.data];
+                    const values = dataFields
+                        .map(field => item[field])
                         .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);
-                    }
-                }
+                    if (!values.length) return [];
+
+                    const value = values.join(config.separator || ':');
+                    const tag = [
+                        config.prefix,
+                        value,
+                        config.suffix
+                    ].filter(Boolean).join('');
+                    return [tag];
+                });
+            }
+
+            // Handle param-based tags
+            if (config.param) {
+                const paramFields = Array.isArray(config.param) ? config.param : [config.param];
+                const values = paramFields
+                    .map(field => params[field])
+                    .filter(Boolean);
+
+                if (!values.length) return [];
+
+                const value = values.join(config.separator || ':');
+                const tag = [
+                    config.prefix,
+                    value,
+                    config.suffix
+                ].filter(Boolean).join('');
+                return [tag];
             }
+
+            return [];
         });
 
         // Remove duplicates
@@ -451,13 +460,13 @@ class CachingService extends cds.Service {
                 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 
+                    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) {