cds-caching 1.1.0 → 1.2.0

package/README.md

@@ -37,10 +37,36 @@ Please also read the introduction blog post in the SAP Community: [Boosting perf
 > - [Metrics Guide](docs/metrics-guide.md)
 > - [OData API Reference](docs/odata-api.md)
 
-## 🚨 Breaking Changes: Migrating from cds-caching 0.x
+## 🚨 Breaking Changes: Migrating cds-caching
 
 > **⚠️ Important:** Version 1.x contains breaking changes. Please review the migration guide below.
 
+## Upgrading from 1.1.0 to 1.2.0
+
+From **1.2.0** onwards, storage/compression adapters are treated as **optional peer dependencies** and must be installed **explicitly in your consuming CAP project** (i.e. *your app*, not `cds-caching`). This avoids relying on transitive dependencies and makes adapter usage deterministic.
+
+### Required adapter packages (add to your app's `package.json`)
+
+Install the package(s) matching your configured `store` / `compression`:
+
+| Config | Value | Install in your app |
+|---|---|---|
+| `store` | `"redis"` | `@keyv/redis` |
+| `store` | `"sqlite"` | `@resolid/keyv-sqlite` (recommended) **or** `@keyv/sqlite` |
+| `store` | `"postgres"` | `@keyv/postgres` |
+| `compression` | `"lz4"` | `@keyv/compress-lz4` |
+| `compression` | `"gzip"` | `@keyv/compress-gzip` |
+
+Example:
+
+```bash
+npm i @keyv/redis
+# or: npm i @resolid/keyv-sqlite
+# and optionally: npm i @keyv/compress-gzip
+```
+
+## Upgrading from 0.x to 1.x
+
 ### 🔄 API Changes for read-through methods
 
 Version 1.x introduces new methods that provide more insights into the read-through caching as they also directly return the genrated cache `key` and some caching `metadata`. The should be preferrably used instead of the old methods.
@@ -159,6 +185,25 @@ Installing and using cds-caching is straightforward since it's a CAP plugin. Sim
 npm install cds-caching
 ```
 
+#### Adapter packages (Redis / SQLite / Compression)
+
+`cds-caching` only ships with the in-memory store. If you configure a different store or compression, you must install the corresponding adapter package **in your consuming CAP project**:
+
+```bash
+# Redis store
+npm install @keyv/redis
+
+# SQLite store
+npm install @resolid/keyv-sqlite  # Preferred in CAP because of better-sqlite3 usage
+npm install @keyv/sqlite          # Alternative if you want to rely on the official adapter
+
+# Compression
+npm install @keyv/compress-lz4   # for "lz4"
+npm install @keyv/compress-gzip  # for "gzip"
+```
+
+If you configure an adapter but don’t have its package installed, `cds-caching` will fail fast with a clear error telling you what to install.
+
 ### Configuration
 
 The cds-caching plugin supports comprehensive configuration through `package.json`. Here are all available configuration options:
@@ -197,6 +242,7 @@ The cds-caching plugin supports comprehensive configuration through `package.jso
         "store": "in-memory", // "in-memory", "sqlite", or "redis"
         "compression": "lz4", // "lz4" or "gzip"
         "throwOnErrors": false, // Whether basic operations should throw errors (default: false)
+        "transactionalOperations": false, // When true, basic ops run in a dedicated cache tx (cache.tx())
         "credentials": {
           // Redis configuration
           "host": "localhost",
@@ -215,6 +261,27 @@ The cds-caching plugin supports comprehensive configuration through `package.jso
 }
 ```
 
+#### Transaction isolation for basic operations (`transactionalOperations`)
+
+CAP can run multiple `before` handlers concurrently. If one handler fails and rolls back the request transaction, other concurrent handlers may still be running and can fail when they access the cache (typical error: “Transaction is rolled back, no subsequent .run allowed…”).
+
+To isolate **basic cache operations** (`get`, `set`, `delete`, `clear`, `deleteByTag`, `metadata`, `tags`, `getRaw`) from the request transaction, enable:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "caching": {
+        "impl": "cds-caching",
+        "transactionalOperations": true
+      }
+    }
+  }
+}
+```
+
+In the background, the caching service opens a dedicated cache transaction via `cache.tx()`, executes the operation via `tx.send(...)`, and commits/rolls back the cache transaction per operation. This keeps cache calls working even if the surrounding request transaction is already rolled back.
+
 #### Read-Through (RT) Key Configuration
 
 Configure default key templates for read-through operations:
@@ -323,12 +390,14 @@ cds-caching provides 3 storage options:
 - Memory on SAP BTP Cloud Foundry is limited (up to 16 GB) and produces costs
 
 ##### SQLite (for medium-size use uses)
+- Requires installing the adapter package: `@keyv/sqlite` (in your project)
 - 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)
+- Requires installing the adapter package: `@keyv/redis` (in your project)
 - 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)

package/lib/CachingService.d.ts

@@ -124,6 +124,12 @@ export declare class CachingService extends Service {
     compression: any;
     credentials: Record<string, any>;
     namespace?: string;
+    throwOnErrors?: boolean;
+    /**
+     * When enabled, basic operations (`get`, `set`, `delete`, ...) run in a dedicated cache transaction.
+     * This isolates cache access from the caller's request transaction (useful for concurrent BEFORE handlers).
+     */
+    transactionalOperations?: boolean;
   };
   
   private cacheAnnotatedFunctions: {
@@ -146,52 +152,52 @@ export declare class CachingService extends Service {
   /**
    * Set a value in the cache
    */
-  set(key: string | object, value: any, options?: CacheOptions): Promise<void>;
+  set(key: string | object, value: any, options?: CacheOptions, tx?: any): Promise<void>;
 
   /**
    * Get a value from the cache
    */
-  get(key: string | object): Promise<any>;
+  get(key: string | object, tx?: any): Promise<any>;
 
   /**
    * Check if a key exists in the cache
    */
-  has(key: string | object): Promise<boolean>;
+  has(key: string | object, tx?: any): Promise<boolean>;
 
   /**
    * Delete a key from the cache
    */
-  delete(key: string | object): Promise<boolean>;
+  delete(key: string | object, tx?: any): Promise<boolean>;
 
   /**
    * Clear all cache entries
    */
-  clear(): Promise<void>;
+  clear(tx?: any): Promise<void>;
 
   /**
    * Delete all keys that have a specific tag
    */
-  deleteByTag(tag: string): Promise<void>;
+  deleteByTag(tag: string, tx?: any): Promise<void>;
 
   /**
    * Get metadata for a key
    */
-  metadata(key: string | object): Promise<CacheMetadata | null>;
+  metadata(key: string | object, tx?: any): Promise<CacheMetadata | null>;
 
   /**
    * Get tags for a key
    */
-  tags(key: string | object): Promise<string[]>;
+  tags(key: string | object, tx?: any): Promise<string[]>;
 
   /**
    * Iterator for all cache entries
    */
-  iterator(): AsyncIterableIterator<[string, CacheMetadata]>;
+  iterator(tx?: any): AsyncIterableIterator<[string, CacheMetadata]>;
 
   /**
    * Get a raw value from the cache without statistics tracking
    */
-  getRaw(key: string | object): Promise<any>;
+  getRaw(key: string | object, tx?: any): Promise<any>;
 
   // ============================================================================
   // Deprecated CAP Operations (for backward compatibility)

package/lib/CachingService.js

@@ -13,13 +13,19 @@ class CachingService extends cds.Service {
     async init() {
         super.init()
         this.log = cds.log('cds-caching')
-        this.options = this.options || {
+        this.options = {
             store: null,
             compression: null,
             credentials: {},
             namespace: null,
             throwOnErrors: false,
+            // When enabled, basic cache operations (`get`, `set`, `delete`, ...)
+            // will be executed in a dedicated cache transaction (`cache.tx()`),
+            // isolating them from the caller's request transaction (e.g. concurrent BEFORE handlers).
+            transactionalOperations: false,
+            ...(this.options || {})
         };
+        this.options.credentials = this.options.credentials || {};
 
         // Initialize managers
         this.storeManager = new CacheStoreManager();
@@ -130,15 +136,61 @@ class CachingService extends cds.Service {
 
     createKey(...args) { return this.keyManager.createKey(...args); }
 
-    async set(...args) { return this.basicOperations.set(...args); }
-    async get(...args) { return this.basicOperations.get(...args); }
-    async has(...args) { return this.basicOperations.has(...args); }
-    async delete(...args) { return this.basicOperations.delete(...args); }
-    async clear(...args) { return this.basicOperations.clear(...args); }
-    async deleteByTag(...args) { return this.basicOperations.deleteByTag(...args); }
-    async metadata(...args) { return this.basicOperations.metadata(...args); }
-    async tags(...args) { return this.basicOperations.tags(...args); }
-    async *iterator(...args) { return yield* this.basicOperations.iterator(...args); }
+    async set(key, value, options = {}, tx = null) {
+        if (tx) return this.basicOperations.set(key, value, options, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.setInTx(key, value, options);
+        return this.basicOperations.set(key, value, options);
+    }
+
+    async get(key, tx = null) {
+        if (tx) return this.basicOperations.get(key, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.getInTx(key);
+        return this.basicOperations.get(key);
+    }
+
+    async has(key, tx = null) {
+        // `has()` bypasses CAP tx handling in BasicOperations, so the `tx` argument is ignored.
+        // It is accepted here for API symmetry.
+        return this.basicOperations.has(key, tx);
+    }
+
+    async delete(key, tx = null) {
+        if (tx) return this.basicOperations.delete(key, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.deleteInTx(key);
+        return this.basicOperations.delete(key);
+    }
+
+    async clear(tx = null) {
+        if (tx) return this.basicOperations.clear(tx);
+        if (this.options.transactionalOperations) return this.basicOperations.clearInTx();
+        return this.basicOperations.clear();
+    }
+
+    async deleteByTag(tag, tx = null) {
+        if (tx) return this.basicOperations.deleteByTag(tag, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.deleteByTagInTx(tag);
+        return this.basicOperations.deleteByTag(tag);
+    }
+
+    async metadata(key, tx = null) {
+        if (tx) return this.basicOperations.metadata(key, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.metadataInTx(key);
+        return this.basicOperations.metadata(key);
+    }
+
+    async tags(key, tx = null) {
+        if (tx) return this.basicOperations.tags(key, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.tagsInTx(key);
+        return this.basicOperations.tags(key);
+    }
+
+    async getRaw(key, tx = null) {
+        if (tx) return this.basicOperations.getRaw(key, tx);
+        if (this.options.transactionalOperations) return this.basicOperations.getRawInTx(key);
+        return this.basicOperations.getRaw(key);
+    }
+
+    async *iterator(tx = null) { return yield* this.basicOperations.iterator(tx); }
 
     // ============================================================================
     // PUBLIC API - Read Through Operations

package/lib/operations/BasicOperations.js

@@ -9,6 +9,16 @@ class BasicOperations {
         this.statistics = statistics;
     }
 
+    _keyv() {
+        // The underlying Keyv instance is stored on the CachingService as `this.cache`
+        // (see `CachingService.init()` where `this.cache = new Keyv(...)`).
+        const keyv = this.cache?.cache;
+        if (!keyv) {
+            throw new Error('cds-caching: Keyv store not initialized on caching service');
+        }
+        return keyv;
+    }
+
     /**
      * Set a value in the cache
      * @param {string|object} key - the key to set
@@ -16,14 +26,17 @@ class BasicOperations {
      * @param {object} options - cache options
      * @returns {Promise<void>}
      */
-    async set(key, value, options = {}) {
+    async set(key, value, options = {}, tx = null) {
         const wrappedValue = {
             value,
             tags: this.tagResolver.resolveTags(options.tags, value, options.params) || [],
             timestamp: Date.now()
         };
         const createdKey = this.keyManager.createKey(key, {}, options.key);
-        await this.cache.send('SET', {
+        // If no key was created, the input should not be cached (e.g. non-SELECT CQN)
+        if (!createdKey) return;
+        const srv = tx || this.cache;
+        await srv.send('SET', {
             key: createdKey,
             value: wrappedValue,
             ttl: options.ttl || 0
@@ -44,9 +57,16 @@ class BasicOperations {
      * @param {string|object} key - the key to get
      * @returns {Promise<any>} - the cached value
      */
-    async get(key) {
+    async get(key, tx = null) {
         const createdKey = this.keyManager.createKey(key);
-        const wrappedValue = await this.cache.send('GET', {
+        
+        // If not key was created, return undefined
+        if(!createdKey) {
+            return undefined;
+        }
+
+        const srv = tx || this.cache;
+        const wrappedValue = await srv.send('GET', {
             key: createdKey
         });
 
@@ -68,10 +88,14 @@ class BasicOperations {
      * @param {string|object} key - the key to check
      * @returns {Promise<boolean>} - whether the key exists
      */
-    async has(key) {
+    async has(key, tx = null) {
         const createdKey = this.keyManager.createKey(key);
+        if (!createdKey) return false;
         try {
-            return await this.cache.cache.has(createdKey);
+            // Intentionally bypass CAP service/transaction handling here.
+            // This avoids coupling to the caller's request tx (which might already be rolled back)
+            // and makes `has()` safe to call even in concurrent BEFORE handlers.
+            return await this._keyv().has(createdKey);
         } catch (error) {
             if (this.cache.options.throwOnErrors) {
                 throw error;
@@ -86,9 +110,11 @@ class BasicOperations {
      * @param {string|object} key - the key to delete
      * @returns {Promise<boolean>} - whether the key was deleted
      */
-    async delete(key) {
+    async delete(key, tx = null) {
         const createdKey = this.keyManager.createKey(key);
-        const result = await this.cache.send('DELETE', {
+        if (!createdKey) return false;
+        const srv = tx || this.cache;
+        const result = await srv.send('DELETE', {
             key: createdKey
         });
 
@@ -108,8 +134,9 @@ class BasicOperations {
      * Clear all cache entries
      * @returns {Promise<void>}
      */
-    async clear() {
-        await this.cache.send('CLEAR', {
+    async clear(tx = null) {
+        const srv = tx || this.cache;
+        await srv.send('CLEAR', {
             deleteAll: true
         });
 
@@ -129,10 +156,11 @@ class BasicOperations {
      * @param {string} tag - the tag to match
      * @returns {Promise<void>}
      */
-    async deleteByTag(tag) {
+    async deleteByTag(tag, tx = null) {
+        // Iterate directly on the underlying store to avoid recursion via CachingService.iterator()
         for await (const [key, wrappedValue] of this.iterator()) {
             if (wrappedValue?.tags?.includes(tag)) {
-                await this.delete(key);
+                await this.delete(key, tx);
             }
         }
 
@@ -152,9 +180,11 @@ class BasicOperations {
      * @param {string|object} key - the key to get metadata for
      * @returns {Promise<object|null>} - the metadata or null if not found
      */
-    async metadata(key) {
+    async metadata(key, tx = null) {
         const createdKey = this.keyManager.createKey(key);
-        const wrappedValue = await this.cache.send('GET', {
+        if (!createdKey) return null;
+        const srv = tx || this.cache;
+        const wrappedValue = await srv.send('GET', {
             key: createdKey
         });
         if (!wrappedValue) return null;
@@ -168,9 +198,11 @@ class BasicOperations {
      * @param {string|object} key - the key to get tags for
      * @returns {Promise<string[]>} - the tags
      */
-    async tags(key) {
+    async tags(key, tx = null) {
         const createdKey = this.keyManager.createKey(key);
-        const wrappedValue = await this.cache.send('GET', {
+        if (!createdKey) return [];
+        const srv = tx || this.cache;
+        const wrappedValue = await srv.send('GET', {
             key: createdKey
         });
         return wrappedValue?.tags || [];
@@ -181,9 +213,11 @@ class BasicOperations {
      * @param {string|object} key - the key to get
      * @returns {Promise<any>} - the raw cached value
      */
-    async getRaw(key) {
+    async getRaw(key, tx = null) {
         const createdKey = this.keyManager.createKey(key);
-        const wrappedValue = await this.cache.send('GET', {
+        if (!createdKey) return undefined;
+        const srv = tx || this.cache;
+        const wrappedValue = await srv.send('GET', {
             key: createdKey
         });
         return wrappedValue?.value;
@@ -193,8 +227,9 @@ class BasicOperations {
      * Iterator for all cache entries
      * @returns {AsyncIterator} - iterator for cache entries
      */
-    async *iterator() {
-        for await (const [key, value] of this.cache.cache.iterator()) {
+    async *iterator(tx = null) {
+        // Iterate directly on Keyv to avoid recursion via CachingService.iterator()
+        for await (const [key, value] of this._keyv().iterator()) {
             if (typeof value === "string") {
                 try {
                     yield [key, JSON.parse(value)];
@@ -206,6 +241,107 @@ class BasicOperations {
             }
         }
     }
+
+    async setInTx(key, value, options = {}) {
+        const tx = await this.cache.tx();
+        try {
+            await this.set(key, value, options, tx);
+            await tx.commit();
+            return;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async getInTx(key) {
+        const tx = await this.cache.tx();
+        try {
+            const value = await this.get(key, tx);
+            await tx.commit();
+            return value;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async hasInTx(key) {
+        // `has()` bypasses CAP tx handling on purpose, so opening a new transaction is unnecessary.
+        return this.has(key);
+    }
+
+    async deleteInTx(key) {
+        const tx = await this.cache.tx();
+        try {
+            const value = await this.delete(key, tx);
+            await tx.commit();
+            return value;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async clearInTx() {
+        const tx = await this.cache.tx();
+        try {
+            await this.clear(tx);
+            await tx.commit();
+            return;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async deleteByTagInTx(tag) {
+        const tx = await this.cache.tx();
+        try {
+            await this.deleteByTag(tag, tx);
+            await tx.commit();
+            return;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async metadataInTx(key) {
+        const tx = await this.cache.tx();
+        try {
+            const value = await this.metadata(key, tx);
+            await tx.commit();
+            return value;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async tagsInTx(key) {
+        const tx = await this.cache.tx();
+        try {
+            const value = await this.tags(key, tx);
+            await tx.commit();
+            return value;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
+
+    async getRawInTx(key) {
+        const tx = await this.cache.tx();
+        try {
+            const value = await this.getRaw(key, tx);
+            await tx.commit();
+            return value;
+        } catch (error) {
+            await tx.rollback();
+            throw error;
+        }
+    }
 }
 
 module.exports = BasicOperations; 

package/lib/operations/CapOperations.js

@@ -28,7 +28,7 @@ class CapOperations {
     async safeCacheOperation(operation, operationName, context = {}) {
         try {
             const result = await operation();
-            this.log.info('REEEESULT', { result });
+            this.log.info('RESULT', { result, operationName, context });
             return { success: true, result, error: null };
         } catch (error) {
             this.log.warn(`Cache ${operationName} failed:`, {
@@ -500,8 +500,6 @@ class CapOperations {
      */
     extractMetadataFromRequest(req) {
 
-        console.log(JSON.stringify(req.http?.req, null, 2));
-
         const metadata = {
             dataType: req.constructor.name,
             serviceName: req.target?.name || '',

package/lib/support/CacheStoreManager.js

@@ -1,8 +1,5 @@
 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 { requireOptional, requireAnyOptional } = require('./optionalRequire');
 
 /**
  * Manages cache store initialization and configuration
@@ -21,7 +18,7 @@ class CacheStoreManager {
      */
     createStore(options, cacheName) {
         const store = this._createStoreInstance(options);
-        const cacheOptions = this._createCacheOptions(options, cacheName);
+        const cacheOptions = this._createCacheOptions(options, cacheName, store);
         const cache = new Keyv(cacheOptions);
         cache.throwOnErrors = options.throwOnErrors;
 
@@ -43,31 +40,47 @@ class CacheStoreManager {
     _createStoreInstance(options) {
         switch (options.store) {
             case "sqlite":
+                // Support both adapters:
+                // - @keyv/sqlite (default export)
+                // - @resolid/keyv-sqlite (named export KeyvSqlite) https://github.com/huijiewei/keyv-sqlite
+                const sqliteMod = requireAnyOptional(['@keyv/sqlite', '@resolid/keyv-sqlite'], { feature: 'store', value: 'sqlite' });
+                const KeyvSqlite = sqliteMod?.KeyvSqlite ?? sqliteMod?.default ?? sqliteMod;
                 return new KeyvSqlite({
                     url: options.credentials?.url,
                     table: options.credentials?.table || 'cache',
                     busyTimeout: options.credentials?.busyTimeout || 10000
                 });
             case "redis":
+                const KeyvRedis = requireOptional('@keyv/redis', { feature: 'store', value: 'redis' });
                 const store = new KeyvRedis({
                     ...options.credentials,
                     ...(options.credentials?.uri ? { url: options.credentials?.uri } : {}),
                     ...{ throwOnConnectErrors: options.throwOnErrors, useKeyPrefix: false, throwOnErrors: options.throwOnErrors }
                 });
 
+                // see https://keyv.org/docs/storage-adapters/redis/#gracefully-handling-errors-and-timeouts for more details
                 if (options.throwOnErrors) {
                     store.throwOnConnectErrors = false; // We want to handle the errors ourselves
-                    store.throwOnErrors = true;
+                    store.throwOnErrors = true; // Redis will throw errors for connection issues, etc.
                     const redisClient = store.client;
                     if (redisClient.options) {
                         redisClient.options.disableOfflineQueue = true;
                         if (redisClient.options.socket) {
-                            redisClient.options.socket.reconnectStrategy = false;
+                            redisClient.options.socket.reconnectStrategy = false; // Disable automatic reconnection
                         }
                     }
                 }
 
                 return store;
+            case "postgres":
+                const KeyvPostgres = requireOptional('@keyv/postgres', { feature: 'store', value: 'postgres' });
+                return new KeyvPostgres({
+                    ...options.credentials,
+                    ...(options.credentials?.url ? { uri: options.credentials?.url } : options.credentials?.uri ? { url: options.credentials?.uri } : {}),
+                    ...(options.credentials?.schema ? { schema: options.credentials?.schema } : {}),
+                    ...(options.credentials?.table ? { table: options.credentials?.table } : {}),
+                    ...{ throwOnConnectErrors: options.throwOnErrors, useKeyPrefix: false, throwOnErrors: options.throwOnErrors }
+                });
             default:
                 return new Map();
         }
@@ -77,11 +90,12 @@ class CacheStoreManager {
      * Create cache options object
      * @private
      */
-    _createCacheOptions(options, cacheName) {
+    _createCacheOptions(options, cacheName, store) {
         return {
             namespace: options.namespace || cacheName,
-            store: this._createStoreInstance(options),
-            compression: this._createCompression(options.compression)
+            store,
+            compression: this._createCompression(options.compression),
+            useKeyPrefix: store.constructor.name === 'KeyvRedis' ? false : true // see https://github.com/mikezaschka/cds-caching/issues/11
         };
     }
 
@@ -92,8 +106,10 @@ class CacheStoreManager {
     _createCompression(compressionType) {
         switch (compressionType) {
             case "lz4":
+                const KeyvLz4 = requireOptional('@keyv/compress-lz4', { feature: 'compression', value: 'lz4' });
                 return new KeyvLz4();
             case "gzip":
+                const KeyvGzip = requireOptional('@keyv/compress-gzip', { feature: 'compression', value: 'gzip' });
                 return new KeyvGzip();
             default:
                 return undefined;

package/lib/support/optionalRequire.js

@@ -0,0 +1,45 @@
+function isMissingModuleError(err, packageName) {
+  const msg = String(err?.message || '');
+  return (
+    (err?.code === 'MODULE_NOT_FOUND' || err?.code === 'ERR_MODULE_NOT_FOUND') &&
+    (msg.includes(`'${packageName}'`) || msg.includes(`"${packageName}"`) || msg.includes(packageName))
+  );
+}
+
+function requireOptional(packageName, { feature, value } = {}) {
+  try {
+    const mod = require(packageName);
+    return mod?.default ?? mod;
+  } catch (err) {
+    if (!isMissingModuleError(err, packageName)) throw err;
+
+    const featureText = feature ? `${feature}="${value}" ` : '';
+    throw new Error(`cds-caching: ${featureText}requires installing "${packageName}" (npm i ${packageName})`);
+  }
+}
+
+function requireAnyOptional(packageNames, { feature, value } = {}) {
+  const missing = [];
+  for (const packageName of packageNames) {
+    try {
+      return require(packageName);
+    } catch (err) {
+      if (isMissingModuleError(err, packageName)) {
+        missing.push(packageName);
+        continue;
+      }
+      throw err;
+    }
+  }
+
+  const featureText = feature ? `${feature}="${value}" ` : '';
+  const pkgsQuoted = missing.map((p) => `"${p}"`).join(' or ');
+  const pkgsInstall = missing.map((p) => `npm i ${p}`).join(' OR ');
+  throw new Error(`cds-caching: ${featureText}requires installing ${pkgsQuoted} (${pkgsInstall})`);
+}
+
+module.exports = {
+  requireOptional,
+  requireAnyOptional
+};
+

package/lib/util.js

@@ -93,7 +93,7 @@ const bindEntity = async (service, entity) => {
 const createCacheEntry = async (cacheName, serviceConfig = {}) => {
     try {
         const db = await cds.connect.to('db');
-        const { Caches } = db.entities('plugin.cds_caching');
+        const { Caches } = cds.entities('plugin.cds_caching');
 
         // Check if cache entry already exists
         const existingCache = await db.read(Caches).where({ name: cacheName });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cds-caching",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "A caching plugin for SAP CAP applications",
   "repository": {
     "type": "git",
@@ -34,7 +34,33 @@
     "release": "release-it"
   },
   "peerDependencies": {
-    "@sap/cds": ">=8"
+    "@sap/cds": ">=8",
+    "@keyv/compress-gzip": "^2.0.3",
+    "@keyv/compress-lz4": "^1.0.1",
+    "@keyv/redis": "^5.0.0",
+    "@keyv/sqlite": "^4.0.5",
+    "@resolid/keyv-sqlite": "^4.0.5",
+    "@keyv/postgres": "^4.0.5"
+  },
+  "peerDependenciesMeta": {
+    "@keyv/redis": {
+      "optional": true
+    },
+    "@keyv/sqlite": {
+      "optional": true
+    },
+    "@keyv/compress-lz4": {
+      "optional": true
+    },
+    "@keyv/compress-gzip": {
+      "optional": true
+    },
+    "@resolid/keyv-sqlite": {
+      "optional": true
+    },
+    "@keyv/postgres": {
+      "optional": true
+    }
   },
   "workspaces": [
     ".",
@@ -43,21 +69,22 @@
     "examples/app"
   ],
   "dependencies": {
-    "@keyv/compress-gzip": "^2.0.3",
-    "@keyv/compress-lz4": "^1.0.1",
-    "@keyv/redis": "^5.0.0",
-    "@keyv/sqlite": "^4.0.5",
-    "keyv": "^5.4.0"
+    "keyv": "^5.6.0"
   },
   "devDependencies": {
-    "@cap-js/cds-test": "^0.4.0",
-    "@release-it/conventional-changelog": "^10.0.1",
-    "eslint": "^9.32.0",
+    "@cap-js/cds-test": "^0.4.1",
+    "@release-it/conventional-changelog": "^10.0.5",
+    "eslint": "^10.0.0",
     "husky": "^9.1.7",
-    "jest": "^30.0.5",
-    "release-it": "^19.0.4"
+    "jest": "^30.2.0",
+    "release-it": "^19.2.4",
+    "@resolid/keyv-sqlite": "~5.0.1",
+    "@keyv/sqlite": "~4.0.8",
+    "@keyv/compress-lz4": "~1.0.1",
+    "@keyv/compress-gzip": "~2.0.3",
+    "@keyv/postgres": "~2.2.3"
   },
   "engines": {
-    "node": ">=20"
+    "node": ">=24"
   }
 }