cds-caching 0.2.1 → 0.3.1

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,
@@ -98,12 +105,19 @@ For more control, you can specify additional options:
 
 #### Storage Options
 
-cds-caching provides two storage options:
+cds-caching provides 3 storage options:
 
-##### In-Memory Cache (for small-scale use)
+##### 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
@@ -111,7 +125,7 @@ cds-caching provides two storage options:
 - Available on SAP BTP via hyperscaler options (e.g., AWS, Azure, Google Cloud)
 - Even trial accounts provide Redis access
 
-#### Development Setup
+#### 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:
@@ -237,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)
@@ -256,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.
+
+
+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.
+
+
+```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()
+  }
+}
+```
 
-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. 
+#### 5. ApplicationService Request-Level Caching with Annotations
 
-**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.**
+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 {
@@ -753,4 +796,4 @@ Contributions are welcome! Please read our contributing guidelines and submit pu
 
 ### License
 
-This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
+This project is licensed under the MIT License - see the LICENSE file for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cds-caching",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "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) {

package/srv/util.js

@@ -1,5 +1,20 @@
 const cds = require("@sap/cds")
 
+const extractCacheProperties = (entity, prefix) => {
+    const result = {};
+    for (const key of Object.keys(entity)) {
+        if (key.startsWith(`@cache.${prefix}.`)) {
+            const subKey = key.substring(`@cache.${prefix}.`.length);
+            result[subKey] = entity[key];
+        }
+    }
+    // If there are no subproperties but the main property exists, use it directly
+    if (Object.keys(result).length === 0 && entity[`@cache.${prefix}`]) {
+        return entity[`@cache.${prefix}`];
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+};
+
 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);
@@ -9,8 +24,8 @@ const bindFunction = async (service, action, isBound = false) => {
             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']
+                tags: extractCacheProperties(action, 'tags'),
+                key: extractCacheProperties(action, 'key')
             });
             return data;
         })
@@ -21,10 +36,11 @@ 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']
+                tags: extractCacheProperties(entity, 'tags'),
+                key: extractCacheProperties(entity, 'key')
             });
             return data;
         })