@cap-js-community/common
Advanced tools
npm add @cap-js-community/common in @sap/cds projectThis project provides common functionality for CDS services to be consumed with SAP Cloud Application Programming Model (Node.js).
The replication cache allows to cache a service (e.g. db service) into a tenant-aware SQLite database. Local replicated SQLite database can be queried with same query as the original service.
@cds.replicate
entity Books {
key ID : Integer;
title : localized String;
descr : localized String;
}
Annotations can be used to enable replication cache for a service on entity level:
@cds.replicate: Boolean | Object: Enable replication cache for entity
@cds.replicate.ttl: Number: Time-To-Live (TTL) of cache entry in milliseconds@cds.replicate.auto: Boolean: Replication is managed automatically@cds.replicate.preload: Boolean: Preload replication for entity@cds.replicate.group: String: Replication group name@cds.replicate.static: Boolean: Statically replicate non-tenant awareDefaults are taken from CDS environment.
Options can be passed to replication cache via CDS environment via cds.replicationCache section:
plugin: Boolean: Replication cache is activated via CDS plugin for db service. Default is truename: String: Service name. Default is "db"group: String: Replication group name. Default is "default"credentials: Object: SQLite credentials
database: String: Database file. Default is ":memory:" and in production: "data.sqlite"ttl: Number: Time-To-Live (TTL) of cache entries in milliseconds. Default is 1800000 (30 minutes)check: Number: Interval to check size and prune. Default is 60000 (1 minute)stats: Number: Interval to log statistics. Default is 300000 (5 minutes)size: Number: Maximal cache size in bytes. Default is 10485760 (10 MB) and in production: 104857600 (100 MB)pipe: Boolean: Replication is streamed through pipeline. chunks is not used. Default is truechunks: Number: Replication chunk size. Default is 1000retries: Number: Replication retries for failed replications. Default is 3auto: Boolean: Replication is managed automatically. Default is trueprune: Boolean: Check and prune directly after replication. Default is truevalidate: Boolean: Validate count of replicated records. Default is truedeploy: Boolean: Deploy whole schema to allow queries on projections. Default is truepreload: Boolean: Preload all replication enables entity. Default is falsewait: Boolean: Delay read query until replication finished. Default is falsesearch: Boolean: Search queries are allowed on replication cache. Default is truemeasure: Boolean: Measure and compare replication cache and service query execution. Default is falsetmpDir: Boolean: Store replication cache file in temporary directory. Default is falsebaseDir: String: Base directory for replication cache files. Default is "temp"Replication cache is inactive per default for tests (test profile). It can be enabled via CDS env:
{
"cds": {
"replicationCache": {
"[test]": {
"plugin": true
}
}
}
}
The migration check allows to check for incompatible changes in the CDS model and
to maintain a whitelist for compatible changes via cdsmc command line tool.
Options can be passed to migration check via CDS environment via cds.migrationCheck section:
baseDir: String: Specifies the base directory for migration check. Default is "migration-check"whitelist: Boolean: Requires maintaining a whitelist for compatible changes. Default is truecheckMtx: Boolean: Includes CDS MTXS persistence in check. Default is truekeep: Boolean: Keeps whitelist after update, otherwise whitelist is cleared. Default is falsefreeze: Boolean: Freeze the persistence. Event compatible changes are not allowed, Default is falselabel: String: Label to describe the updated hash files in addition to the timestamp. Default is ""buildPath: String: Path to the build CSN. If not specified, it is derived from the CAP project type. Default is nulladminHash: String: Specify admin hash to acknowledge incompatible changes. Default is nulladminTracking: Boolean: Track changes acknowledged by admin in an admin changes file. Default is trueProduction CSN is built for first time when not existing (otherwise it is updated):
cds build --productioncdsmc -uProduction CSN MUST be added to version control.
Migration check is used to check for incompatible changes in a repetitive way along development:
cds build --productioncdsmcIncompatible changes are detected and reported as error. Compatible changes need to be whitelisted (can be disabled via options).
Incompatible Changes:
ReleasedEntityCannotBeRemoved)ReleasedEntityDraftEnablementCannotBeChanged)ReleasedElementCannotBeRemoved)ReleasedElementKeyCannotBeChanged)ReleasedElementManagedUnmanagedCannotBeChanged)ReleasedElementVirtualCannotBeChanged)ReleasedElementLocalizationCannotBeChanged)ReleasedElementNullableCannotBeChanged)ReleasedElementTypeCannotBeChanged)ReleasedElementTypeCannotBeShortened)ReleasedElementScalePrecisionCannotBeLower)ReleasedElementTargetCannotBeChanged)ReleasedElementCardinalityCannotBeChanged)ReleasedElementOnConditionCannotBeChanged)ReleasedElementKeysConditionCannotBeChanged)ReleasedEntityJournalModeAndEntityChangeIsNotAllowed)ReleasedEntityIndexChangeIsNotAllowed)Compatible Changes:
ReleasedEntityIndexChangeIsNotWhitelisted)ReleasedElementTypeExtensionIsNotWhitelisted)ReleasedElementScalePrecisionExtensionIsNotWhitelisted)ReleasedElementTypeChangeIsNotWhitelisted)NewEntityIsNotWhitelisted)NewEntityElementIsNotWhitelisted)NewEntityElementNotNullableDefault)NewEntityIndexIsNotWhitelisted)The Production CSN can be updated when no migration check errors occur:
cds build --productioncdsmc -uProduction CSN MUST be added to version control.
Maintain the whitelist extension file migration-extension-whitelist.json for compatible changes:
Whitelist Entity:
{
"definitions": {
"test.Test": {}
}
}
Whitelist Entity Element:
{
"definitions": {
"test.Test": {
"elements": {
"value": {}
}
}
}
}
Accepted incompatible changes can be acknowledged and will not be reported as error anymore:
cdsmc -acds.migrationCheck.adminHashCDS persistence can be (temporarily) frozen to prevent any changes (also compatible) to the persistence model:
cds.migrationCheck.freezecdsmc -u -a
./csn-prod.freeze is created to indicate that persistence is frozenMigration check can be used in a pipeline (e.g. part of Pull Request voter) to ensure that incompatible changes are not introduced:
cds build --production && cdsmccds build --production && cdsmc -uProduction CSN MUST be added to version control.
The rate limiting allows to limit the number of requests per service and tenant.
@cds.rateLimiting
service BookshopService {
entity Books @readonly as projection on test.Books;
}
@cds.rateLimiting: Boolean: Activate rate limit for service@cds.rateLimiting.maxConcurrent: Number: Maximum number of concurrent requests per service and tenant@cds.rateLimiting.maxInWindow: Number: Maximum number of requests in defined window per service and tenant@cds.rateLimiting.window: Number: Window length in millisecondsOptions can be passed to migration check via CDS environment via cds.rateLimiting section:
plugin: Boolean: Rate limiting is activated via CDS plugin for annotated services. Default is truemaxConcurrent: Boolean: Maximum number of concurrent requests per service and tenant. Default is 3maxWindow: Boolean: Maximum number of requests in defined window per service and tenant. Default is 10000 (10 seconds)window: Boolean: Window length in milliseconds. Default is 3600000 (1 hour)retry: Boolean: Default is 5Redis options can be provided in CDS env as follows:
{
"cds": {
"requires": {
"redis-rateLimiting": {
"vcap": {
"tag": "my-redis"
},
"options": {}
}
}
}
}
For shared redis configuration Redis service name can be provided in CDS env as follows:
{
"cds": {
"requires": {
"redis-rateLimiting": false,
"redis": {
"vcap": {
"tag": "my-redis"
},
"options": {}
}
}
}
}
Rate limiting is inactive per default for tests (test profile). It can be enabled via CDS env:
{
"cds": {
"rateLimiting": {
"[test]": {
"plugin": true
}
}
}
}
A Redis Client broker is provided to connect to Redis service.
const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.default().createMainClientAndConnect(options);
const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.default("name").createMainClientAndConnect(options);
const { RedisClient } = require("@cap-js-community/common");
const client = await new RedisClient("name").createClientAndConnect(options);
Options can be passed to Redis client via CDS environment via cds.redis section:
Redis options can be provided in CDS env as follows:
{
"cds": {
"requires": {
"redis": {
"vcap": {
"tag": "redis-cache"
},
"options": {}
}
}
}
}
Specific Redis options for a custom name can be established as follows:
{
"cds": {
"requires": {
"redis-customName": {
"vcap": {
"tag": "redis-cache"
},
"options": {}
}
}
}
}
const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.default("customName").createMainClientAndConnect(options);
In addition, options can be passed to Redis client during creation via options parameter:
const { RedisClient } = require("@cap-js-community/common");
const mainClient = await RedisClient.default().createMainClientAndConnect(options);
For details on Redis createClient configuration options see Redis Client Configuration.
This project is open to feature requests/suggestions, bug reports etc. via GitHub issues. Contribution and feedback are encouraged and always welcome. For more information about how to contribute, the project structure, as well as additional contribution information, see our Contribution Guidelines.
We as members, contributors, and leaders pledge to make participation in our community a harassment-free experience for everyone. By participating in this project, you agree to abide by its Code of Conduct at all times.
Copyright 2025 SAP SE or an SAP affiliate company and common contributors. Please see our LICENSE for copyright and license information. Detailed information including third-party components and their licensing/copyright information is available via the REUSE tool.
FAQs
CAP Node.js Community Common
The npm package @cap-js-community/common receives a total of 180 weekly downloads. As such, @cap-js-community/common popularity was classified as not popular.
We found that @cap-js-community/common demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 3 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
The Latio podcast explores how static and runtime reachability help teams prioritize exploitable vulnerabilities and streamline AppSec workflows.
Security News
The latest Opengrep releases add Apex scanning, precision rule tuning, and performance gains for open source static code analysis.
Security News
npm now supports Trusted Publishing with OIDC, enabling secure package publishing directly from CI/CD workflows without relying on long-lived tokens.