cds-caching 0.2.0 → 0.2.1

package/README.md

@@ -93,6 +93,97 @@ For more control, you can specify additional options:
 }
 ```
 
+### Real-World Usage and Deployment
+
+
+#### Storage Options
+
+cds-caching provides two storage options:
+
+##### In-Memory Cache (for small-scale use)
+- Simple and fast, but not persistent
+- Not suitable for production since Node.js runtime memory is limited
+- Data is lost when the application restarts
+
+##### 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
+
+#### 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:
@@ -266,7 +357,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 +567,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 +706,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 +716,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.2.1",
   "description": "A caching plugin for SAP CAP applications supporting Redis",
   "repository": {
     "type": "git",