cds-caching 1.0.0 → 1.2.0

package/README.md

@@ -1,4 +1,6 @@
 # Welcome to cds-caching
+[![npm version](https://img.shields.io/npm/v/cds-caching)](https://www.npmjs.com/package/cds-caching/common)
+[![monthly downloads](https://img.shields.io/npm/dm/cds-caching)](https://www.npmjs.com/package/cds-caching)
 
 ## Overview
 
@@ -35,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.
@@ -136,44 +164,45 @@ await cache.set(data, value, {
 
 For detailed API documentation, see [Programmatic API Reference](docs/programmatic-api.md). 
 
-### Installation
+### Example Application
 
-Installing and using cds-caching is straightforward since it's a CAP plugin. Simply run:
+The cds-caching plugin includes a comprehensive example application demonstrating various caching use cases and a UI5-based dashboard for monitoring cache performance.
 
-```bash
-npm install cds-caching
-```
+![Cache Dashboard](./docs/dashboard.jpg)
 
-### TypeScript Support
+The example consists of:
+- **Backend Application** (`examples/app/`) - A CAP application showing annotation-based and programmatic caching patterns
+- **Dashboard** (`examples/dashboard/`) - A UI5-based monitoring interface with real-time metrics, key-level analytics, and historical data
 
-cds-caching includes comprehensive TypeScript definitions. The library is written in JavaScript but provides full TypeScript support for better development experience.
+[See the full Example Application Guide →](docs/example-app.md)
 
-#### Basic Usage with TypeScript
 
-```typescript
-import { CachingService, CacheOptions, ReadThroughResult } from 'cds-caching';
+### Installation
 
-const cache = await cds.connect.to('caching') as CachingService;
+Installing and using cds-caching is straightforward since it's a CAP plugin. Simply run:
 
-// Basic cache operations
-await cache.set('my-key', { data: 'value' }, { ttl: 3600 });
-const value = await cache.get('my-key');
+```bash
+npm install cds-caching
+```
 
-// Read-through operations with full type safety
-const { result, cacheKey, metadata } = await cache.rt.send(request, service, {
-  ttl: 1800,
-  tags: ['user-data']
-});
+#### Adapter packages (Redis / SQLite / Compression)
 
-// Function wrapping with type inference
-const cachedFunction = cache.rt.wrap('expensive-operation', async (id: string) => {
-  return await this.performExpensiveOperation(id);
-});
+`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**:
 
-const { result: operationResult } = await cachedFunction('user-123');
+```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
 
@@ -212,6 +241,8 @@ The cds-caching plugin supports comprehensive configuration through `package.jso
         "namespace": "caching",
         "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",
@@ -230,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:
@@ -253,6 +305,36 @@ Configure default key templates for read-through operations:
 
 **Default behavior** (if not configured): All context elements are disabled by default.
 
+#### Error Handling Configuration
+
+Configure how the caching service handles errors:
+
+```json
+{
+  "cds": {
+    "requires": {
+      "caching": {
+        ...
+        "throwOnErrors": true,      // Basic operations (set, get, delete, has) throw errors
+        // Default: false - operations return undefined/null instead of throwing
+      }
+    }
+  }
+}
+```
+
+**Error Handling Behavior:**
+
+- **Basic Operations** (`set`, `get`, `delete`, `has`):
+  - When `throwOnErrors: false` (default): Operations return `undefined`/`null` on errors
+  - When `throwOnErrors: true`: Operations throw errors for connection issues, etc.
+
+- **Read-Through Operations** (`rt.run`, `rt.send`, `rt.wrap`, `rt.exec`):
+  - Never throw errors, regardless of `throwOnErrors` setting
+  - Include `cacheErrors` array in response when errors occur
+  - Always fetch from remote service when cache operations fail
+  - Log errors for monitoring and debugging
+
 #### Environment-Specific Configuration
 
 You can override settings for different environments:
@@ -308,16 +390,19 @@ 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)
 - Even trial accounts provide Redis access
+- Redis will be non-blocking
 
 #### Redis Development Setup
 
@@ -431,6 +516,31 @@ await cache.delete("bp:1000001")
 await cache.clear()
 ```
 
+**Error Handling for Basic Operations:**
+
+```javascript
+// With throwOnErrors: false (default)
+try {
+  const value = await cache.get("bp:1000001")
+  if (value === undefined) {
+    // Handle cache miss or error
+    console.log("Value not found or cache error occurred")
+  }
+} catch (error) {
+  // Only thrown for non-cache related errors
+  console.error("Unexpected error:", error)
+}
+
+// With throwOnErrors: true
+try {
+  const value = await cache.get("bp:1000001")
+  // Value will be undefined if not found, but errors will be thrown
+} catch (error) {
+  // Errors thrown for connection issues, etc.
+  console.error("Cache error:", error)
+}
+```
+
 #### 2. CQN Query Caching
 
 For more advanced CAP integration, cache CAP's CQN queries directly. By passing in the query, a dynamic key is generated based on the CQN structure of the query. Note, that passing in queries with dynamic parameters (e.g. `SELECT.from(Foo).where({id: 1})`) will result in a different key for each query execution.
@@ -463,6 +573,23 @@ Because the cache key has been dynamically created at runtime, it will also be r
 const { result, cacheKey } = await cache.rt.run(query, db)
 ```
 
+**Error Handling for Read-Through Operations:**
+
+Read-through operations never throw errors, even when cache operations fail. Instead, they include error information in the response:
+
+```javascript
+// Read-through operations always return a result, even on cache errors
+const { result, cacheKey, metadata, cacheErrors } = await cache.rt.run(query, db)
+
+if (cacheErrors && cacheErrors.length > 0) {
+  console.log("Cache errors occurred:", cacheErrors)
+  // Result will be fetched from remote service despite cache errors
+}
+
+// The result is always available, regardless of cache errors
+return result
+```
+
 #### 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 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 (if not configured otherwise).
@@ -770,6 +897,36 @@ for await (const entry of iterator) {
 
 This will return an iterator over all cache entries. You can use this to traverse all cache entries and invalidate them based on a specific condition. You should only use this for small caches (e.g. by using multiple caching services with different namespaces).
 
+### TypeScript Support
+
+cds-caching includes comprehensive TypeScript definitions. The library is written in JavaScript but provides full TypeScript support for better development experience.
+
+#### Basic Usage with TypeScript
+
+```typescript
+import { CachingService, CacheOptions, ReadThroughResult } from 'cds-caching';
+
+const cache = await cds.connect.to('caching') as CachingService;
+
+// Basic cache operations
+await cache.set('my-key', { data: 'value' }, { ttl: 3600 });
+const value = await cache.get('my-key');
+
+// Read-through operations with full type safety
+const { result, cacheKey, metadata } = await cache.rt.send(request, service, {
+  ttl: 1800,
+  tags: ['user-data']
+});
+
+// Function wrapping with type inference
+const cachedFunction = cache.rt.wrap('expensive-operation', async (id: string) => {
+  return await this.performExpensiveOperation(id);
+});
+
+const { result: operationResult } = await cachedFunction('user-123');
+
+```
+
 ### OData Service Caching Considerations
 
 While caching individual requests can improve performance, **caching an entire OData service is generally not recommended**. Here's why:

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,11 +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: {}
+            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();
@@ -128,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
@@ -164,7 +218,8 @@ class CachingService extends cds.Service {
         if (typeof args[0] !== "object" || !args[1].send || typeof args[1] !== "object" || args[0].method !== "GET") {
             return super.send(...args);
         } else {
-            return (await this.rt.send(...args)).result;
+            const result = await this.rt.send(...args);
+            return result.result;
         }
     }
 
@@ -177,7 +232,8 @@ class CachingService extends cds.Service {
         if (typeof args[0] !== "object" && !["Request", "NoaRequest", "ODataRequest", "cds.ql"].includes(args[0].constructor.name)) {
             return super.run(...args);
         } else {
-            return (await this.rt.run(...args)).result;
+            const result = await this.rt.run(...args);  
+            return result.result;
         }
     }