@cap-js-community/common 0.2.8 → 0.3.1

package/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
+## Version 0.3.1 - 2025-11-05
+
+### Fixed
+
+- Rework redis client
+
+## Version 0.3.0 - 2025-11-03
+
+### Fixed
+
+- Refactor replication cache
+- Change `@cap-js/sqlite` to dev dependency
+- Replication cache requires `@cap-js/sqlite` as project dependency (no dev dependency)
+
 ## Version 0.2.8 - 2025-10-13
 
 ### Fixed

package/README.md

@@ -30,6 +30,9 @@ Local replicated SQLite database can be queried with same query as the original
 
 ### Usage
 
+> Replication cache uses SQLite as local database for productive usage.
+> Ensure `@cap-js/sqlite` is installed as dependency (not as dev dependency) in your project.
+
 ```cds
 @cds.replicate
 entity Books {
@@ -325,14 +328,14 @@ A Redis Client broker is provided to connect to Redis service.
 
 ```js
 const { RedisClient } = require("@cap-js-community/common");
-const mainClient = await RedisClient.default().createMainClientAndConnect(options);
+const mainClient = await RedisClient.create().createMainClientAndConnect(options);
 ```
 
 #### Main named singleton
 
 ```js
 const { RedisClient } = require("@cap-js-community/common");
-const mainClient = await RedisClient.default("name").createMainClientAndConnect(options);
+const mainClient = await RedisClient.create("name").createMainClientAndConnect(options);
 ```
 
 #### Custom named
@@ -381,14 +384,14 @@ Specific Redis options for a custom name can be established as follows:
 
 ```js
 const { RedisClient } = require("@cap-js-community/common");
-const mainClient = await RedisClient.default("customName").createMainClientAndConnect(options);
+const mainClient = await RedisClient.create("customName").createMainClientAndConnect(options);
 ```
 
 In addition, options can be passed to Redis client during creation via `options` parameter:
 
 ```js
 const { RedisClient } = require("@cap-js-community/common");
-const mainClient = await RedisClient.default().createMainClientAndConnect(options);
+const mainClient = await RedisClient.create().createMainClientAndConnect(options);
 ```
 
 For details on Redis `createClient` configuration options see [Redis Client Configuration](https://github.com/redis/node-redis/blob/master/docs/client-configuration.md).

package/cds-plugin.js

@@ -3,9 +3,7 @@
 const cds = require("@sap/cds");
 require("./src/common/promise");
 
-const { ReplicationCache, RateLimiting, RedisClient } = require("./src");
-
-const TIMEOUT_SHUTDOWN = 2500;
+const { ReplicationCache, RateLimiting } = require("./src");
 
 if (cds.env.rateLimiting.plugin) {
   cds.on("serving", async (service) => {
@@ -24,25 +22,3 @@ if (cds.env.rateLimiting.plugin) {
 if (cds.env.replicationCache.plugin) {
   cds.replicationCache = new ReplicationCache();
 }
-
-cds.on("shutdown", async () => {
-  await shutdownWebSocketServer();
-});
-
-async function shutdownWebSocketServer() {
-  return await new Promise((resolve, reject) => {
-    const timeoutRef = setTimeout(() => {
-      clearTimeout(timeoutRef);
-      resolve();
-    }, TIMEOUT_SHUTDOWN);
-    RedisClient.closeAllClients()
-      .then((result) => {
-        clearTimeout(timeoutRef);
-        resolve(result);
-      })
-      .catch((err) => {
-        clearTimeout(timeoutRef);
-        reject(err);
-      });
-  });
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cap-js-community/common",
-  "version": "0.2.8",
+  "version": "0.3.1",
   "description": "CAP Node.js Community Common",
   "homepage": "https://cap.cloud.sap/",
   "engines": {
@@ -45,7 +45,6 @@
     "audit": "npm audit --only=prod"
   },
   "dependencies": {
-    "@cap-js/sqlite": "^2.0.3",
     "commander": "^14.0.1",
     "redis": "^4.7.1",
     "verror": "^1.10.1"
@@ -53,10 +52,11 @@
   "devDependencies": {
     "@cap-js-community/common": "./",
     "@cap-js/cds-test": "^0.4.0",
+    "@cap-js/sqlite": "^2.0.3",
     "@sap/cds": "^9.4.3",
     "@sap/cds-common-content": "^3.0.1",
     "@sap/cds-dk": "^9.4.1",
-    "eslint": "^9.36.0",
+    "eslint": "^9.39.1",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jest": "^29.0.1",
     "eslint-plugin-n": "^17.23.1",

package/src/migration-check/MigrationCheck.js

@@ -5,7 +5,7 @@ const path = require("path");
 const fs = require("fs");
 const crypto = require("crypto");
 
-const COMPONENT_NAME = "migrationCheck";
+const COMPONENT_NAME = "/cap-js-community-common/migrationCheck";
 const STRING_DEFAULT_LENGTH = 5000;
 
 const Checks = [releasedEntityCheck, newEntityCheck, uniqueIndexCheck, journalModeCheck];

package/src/rate-limiting/RateLimiting.js

@@ -7,7 +7,7 @@ const redisResetTime = require("./redis/resetTime");
 
 const { connectionCheck } = require("./redis/common");
 
-const COMPONENT_NAME = "rateLimiting";
+const COMPONENT_NAME = "/cap-js-community-common/rateLimiting";
 
 class RateLimiting {
   constructor(service, { maxConcurrent, maxInWindow, window } = {}) {

package/src/rate-limiting/redis/common.js

@@ -4,14 +4,14 @@ const cds = require("@sap/cds");
 
 const { RedisClient } = require("../../redis-client");
 
-const COMPONENT_NAME = "rateLimiting";
+const COMPONENT_NAME = "/cap-js-community-common/rateLimiting";
 
 async function connectionCheck() {
-  return await RedisClient.default(COMPONENT_NAME).connectionCheck();
+  return await RedisClient.create(COMPONENT_NAME).connectionCheck();
 }
 
 async function perform(key, cb, cbFallback, retry = cds.env.rateLimiting.retry) {
-  const client = cds.env.rateLimiting.redis && (await RedisClient.default(COMPONENT_NAME).createMainClientAndConnect());
+  const client = cds.env.rateLimiting.redis && (await RedisClient.create(COMPONENT_NAME).createMainClientAndConnect());
   if (client) {
     const value = await cb(client, key);
     if (value === undefined) {

package/src/redis-client/RedisClient.js

@@ -1,19 +1,29 @@
 "use strict";
 
 const redis = require("redis");
+const cds = require("@sap/cds");
 
-const COMPONENT_NAME = "redisClient";
+const COMPONENT_NAME = "/cap-js-community-common/redisClient";
 const LOG_AFTER_SEC = 5;
+const TIMEOUT_SHUTDOWN = 2500;
 
 class RedisClient {
+  #clusterClient = false;
+  #beforeCloseHandler;
   constructor(name) {
     this.name = name;
     this.log = cds.log(COMPONENT_NAME);
     this.mainClientPromise = null;
-    this.additionalClientPromise = null;
     this.subscriberClientPromise = null;
     this.subscribedChannels = {};
     this.lastErrorLog = Date.now();
+
+    if (!RedisClient._shutdownRegistered) {
+      RedisClient._shutdownRegistered = true;
+      cds.on("shutdown", async () => {
+        await this.closeRedisClients();
+      });
+    }
   }
 
   createMainClientAndConnect(options) {
@@ -32,22 +42,6 @@ class RedisClient {
     return this.mainClientPromise;
   }
 
-  createAdditionalClientAndConnect(options) {
-    if (this.additionalClientPromise) {
-      return this.additionalClientPromise;
-    }
-
-    const errorHandlerCreateClient = (err) => {
-      this.additionalClientPromise?.then?.(this.resilientClientClose);
-      this.log.error("Error from additional redis client", err);
-      this.additionalClientPromise = null;
-      setTimeout(() => this.createAdditionalClientAndConnect(options), LOG_AFTER_SEC * 1000).unref();
-    };
-
-    this.additionalClientPromise = this.createClientAndConnect(options, errorHandlerCreateClient);
-    return this.additionalClientPromise;
-  }
-
   async createClientAndConnect(options, errorHandlerCreateClient, isConnectionCheck) {
     try {
       const client = this.createClientBase(options);
@@ -92,7 +86,8 @@ class RedisClient {
         throw error;
       }
       if (client) {
-        await this.resilientClientClose(client);
+        // NOTE: ignore promise: client should not wait + fn can't throw
+        this.resilientClientClose(client);
         return true;
       }
     } catch (err) {
@@ -119,6 +114,7 @@ class RedisClient {
     };
     try {
       if (credentials?.cluster_mode) {
+        this.#clusterClient = true;
         return redis.createCluster({
           rootNodes: [socketOptions],
           defaults: socketOptions,
@@ -141,14 +137,14 @@ class RedisClient {
         LOG_AFTER_SEC * 1000,
       ).unref();
     };
-    this.subscribeChannels(options, { [channel]: subscribeHandler }, errorHandlerCreateClient);
+    this.subscribeChannels(options, errorHandlerCreateClient);
   }
 
-  subscribeChannels(options, subscribedChannels, errorHandlerCreateClient) {
+  subscribeChannels(options, errorHandlerCreateClient) {
     this.subscriberClientPromise = this.createClientAndConnect(options, errorHandlerCreateClient)
       .then((client) => {
         for (const channel in this.subscribedChannels) {
-          const fn = subscribedChannels[channel];
+          const fn = this.subscribedChannels[channel];
           client._subscribedChannels ??= {};
           if (client._subscribedChannels[channel]) {
             continue;
@@ -193,16 +189,6 @@ class RedisClient {
     this.log.info("Main redis client closed!");
   }
 
-  async closeAdditionalClient() {
-    if (!this.additionalClientPromise) {
-      return;
-    }
-    const client = this.additionalClientPromise;
-    this.additionalClientPromise = null;
-    await this.resilientClientClose(await client);
-    this.log.info("Additional redis client closed!");
-  }
-
   async closeSubscribeClient() {
     if (!this.subscriberClientPromise) {
       return;
@@ -214,9 +200,10 @@ class RedisClient {
   }
 
   async closeClients() {
-    await this.closeMainClient();
-    await this.closeAdditionalClient();
-    await this.closeSubscribeClient();
+    if (this.#beforeCloseHandler) {
+      await this.#beforeCloseHandler();
+    }
+    await Promise.allSettled([this.closeMainClient(), this.closeSubscribeClient()]);
   }
 
   async resilientClientClose(client) {
@@ -229,16 +216,42 @@ class RedisClient {
     }
   }
 
-  static default(name = "default") {
-    RedisClient._default ??= {};
-    if (!RedisClient._default[name]) {
-      RedisClient._default[name] = new RedisClient(name);
+  async closeRedisClients() {
+    return await new Promise((resolve, reject) => {
+      const timeoutRef = setTimeout(() => {
+        clearTimeout(timeoutRef);
+        resolve();
+      }, TIMEOUT_SHUTDOWN);
+      RedisClient.closeAllClients()
+        .then((result) => {
+          clearTimeout(timeoutRef);
+          resolve(result);
+        })
+        .catch((err) => {
+          clearTimeout(timeoutRef);
+          reject(err);
+        });
+    });
+  }
+
+  set beforeCloseHandler(cb) {
+    this.#beforeCloseHandler = cb;
+  }
+
+  get isCluster() {
+    return this.#clusterClient;
+  }
+
+  static create(name = "default") {
+    RedisClient._create ??= {};
+    if (!RedisClient._create[name]) {
+      RedisClient._create[name] = new RedisClient(name);
     }
-    return RedisClient._default[name];
+    return RedisClient._create[name];
   }
 
   static async closeAllClients() {
-    for (const entry of Object.values(RedisClient._default || {})) {
+    for (const entry of Object.values(RedisClient._create || {})) {
       await entry.closeClients();
     }
   }

package/src/replication-cache/ReplicationCache.js

@@ -5,8 +5,6 @@ const path = require("path");
 const fs = require("fs").promises;
 
 const cds = require("@sap/cds");
-const SQLiteService = require("@cap-js/sqlite");
-
 require("../common/promise");
 
 const Component = "replicationCache";
@@ -51,7 +49,7 @@ class ReplicationCache {
     this.group = this.options.group;
     this.log = cds.log(Component);
     this.template = null;
-    this.cache = new Map();
+    this.entries = new Map();
     this.initStats();
     this.attach();
   }
@@ -64,6 +62,8 @@ class ReplicationCache {
       if (service.name === this.name) {
         const refs = ReplicationCache.replicationRefs(this.model, service, this.options.deploy);
         if (refs.length > 0) {
+          // @cap-js/sqlite dependency is required for replication cache
+          this.SQLiteService = require("@cap-js/sqlite");
           this.setup(service, refs);
           this.log.info("using replication cache", {
             service: service.name,
@@ -74,7 +74,7 @@ class ReplicationCache {
             this.options?.credentials?.database !== Constants.InMemory
           ) {
             this.log.info("Preparing replication cache template database");
-            this.template = createDB(Tenant.Template, this.model, this.options)
+            this.template = createDB(this.SQLiteService, Tenant.Template, this.model, this.options)
               .then(() => {
                 this.log.info("Prepared replication cache template database");
               })
@@ -220,7 +220,7 @@ class ReplicationCache {
         this.stats.used++;
         this.stats.ratio = Math.round(this.stats.used / this.stats.hits);
         this.log.debug("Replication cache was used");
-        const db = this.cache.get(tenant).db;
+        const db = this.entries.get(tenant).db;
         if (this.options.measure) {
           return this.measure(
             async () => {
@@ -316,15 +316,15 @@ class ReplicationCache {
     if (refs.length === 0) {
       return;
     }
-    let tenantCache = cached(this.cache, tenant, async () => {
-      return new ReplicationCacheTenant(tenant, model, this.options).prepare();
+    let tenantCache = cached(this.entries, tenant, async () => {
+      return new ReplicationCacheTenant(this, tenant, model, this.options).prepare();
     });
     return (async () => {
       try {
         const prepared = Promise.resolve(tenantCache).then(async (tenantCache) => {
           const prepares = [];
           for (const ref of refs) {
-            const entry = cached(tenantCache.cache, ref, () => {
+            const entry = cached(tenantCache.entries, ref, () => {
               return new ReplicationCacheEntry(this, tenantCache, ref);
             });
             entry.touched = Date.now();
@@ -346,7 +346,7 @@ class ReplicationCache {
           return Status.NotReady;
         }
         for (const ref of refs) {
-          const entry = tenantCache.cache.get(ref);
+          const entry = tenantCache.entries.get(ref);
           if (!entry || entry.status !== Status.Ready) {
             return Status.NotReady;
           }
@@ -361,13 +361,13 @@ class ReplicationCache {
   }
 
   async prepared(tenant, ref) {
-    const tenants = tenant ? [tenant] : this.cache.keys();
+    const tenants = tenant ? [tenant] : this.entries.keys();
     for (const id of tenants) {
-      const tenant = await this.cache.get(id);
+      const tenant = await this.entries.get(id);
       if (tenant) {
-        const refs = ref ? [ref] : tenant.cache.keys();
+        const refs = ref ? [ref] : tenant.entries.keys();
         for (const ref of refs) {
-          const entry = tenant.cache.get(ref);
+          const entry = tenant.entries.get(ref);
           if (entry) {
             await entry.prepared;
           }
@@ -377,13 +377,13 @@ class ReplicationCache {
   }
 
   async clear(tenant, ref) {
-    const tenants = tenant ? [tenant] : this.cache.keys();
+    const tenants = tenant ? [tenant] : this.entries.keys();
     for (const id of tenants) {
-      const tenant = await this.cache.get(id);
+      const tenant = await this.entries.get(id);
       if (tenant) {
-        const refs = ref ? [ref] : tenant.cache.keys();
+        const refs = ref ? [ref] : tenant.entries.keys();
         for (const ref of refs) {
-          const entry = tenant.cache.get(ref);
+          const entry = tenant.entries.get(ref);
           if (entry) {
             await entry.clear();
             this.log.debug("Replication cache cleared", {
@@ -404,10 +404,10 @@ class ReplicationCache {
   }
 
   async prune(tenant) {
-    const maxSize = this.options.size / this.cache.size;
-    const tenants = tenant ? [tenant] : this.cache.keys();
+    const maxSize = this.options.size / this.entries.size;
+    const tenants = tenant ? [tenant] : this.entries.keys();
     for (const id of tenants) {
-      const tenant = await this.cache.get(id);
+      const tenant = await this.entries.get(id);
       const size = await this.size(tenant.id);
       let diff = size - maxSize;
       if (diff > 0) {
@@ -415,12 +415,12 @@ class ReplicationCache {
           tenant,
           diff,
         });
-        const refs = [...tenant.cache.keys()];
-        refs.sort((ref1, ref2) => tenant.cache.get(ref1).touched - tenant.cache.get(ref2).touched);
+        const refs = [...tenant.entries.keys()];
+        refs.sort((ref1, ref2) => tenant.entries.get(ref1).touched - tenant.entries.get(ref2).touched);
         const pruneRefs = [];
         for (const ref of refs) {
           pruneRefs.push(ref);
-          const entry = tenant.cache.get(ref);
+          const entry = tenant.entries.get(ref);
           if (entry) {
             diff -= entry.size;
             if (diff <= 0) {
@@ -429,7 +429,7 @@ class ReplicationCache {
           }
         }
         for (const ref of pruneRefs) {
-          const entry = tenant.cache.get(ref);
+          const entry = tenant.entries.get(ref);
           this.log.debug("Replication cache prunes ref for tenant", {
             tenant,
             ref,
@@ -444,13 +444,13 @@ class ReplicationCache {
 
   async size(tenant, ref) {
     let size = 0;
-    const tenants = tenant ? [tenant] : this.cache.keys();
+    const tenants = tenant ? [tenant] : this.entries.keys();
     for (const id of tenants) {
-      const tenant = await this.cache.get(id);
+      const tenant = await this.entries.get(id);
       if (tenant) {
-        const refs = ref ? [ref] : tenant.cache.keys();
+        const refs = ref ? [ref] : tenant.entries.keys();
         for (const ref of refs) {
-          const entry = tenant.cache.get(ref);
+          const entry = tenant.entries.get(ref);
           if (entry) {
             size += entry.size;
           }
@@ -461,7 +461,7 @@ class ReplicationCache {
   }
 
   async tenantSize(id) {
-    const tenant = await this.cache.get(id);
+    const tenant = await this.entries.get(id);
     if (tenant) {
       return await tenant.db.tx(async (tx) => {
         const result = await tx.run(
@@ -578,16 +578,17 @@ class ReplicationCache {
 }
 
 class ReplicationCacheTenant {
-  constructor(tenant, model, options) {
+  constructor(cache, tenant, model, options) {
+    this.cache = cache;
     this.id = tenant;
     this.model = model;
     this.options = options;
     this.csn = model.definitions;
-    this.cache = new Map();
+    this.entries = new Map();
   }
 
   async prepare() {
-    this.db = await createDB(this.id, this.model, this.options);
+    this.db = await createDB(this.cache.SQLiteService, this.id, this.model, this.options);
     return this;
   }
 }
@@ -697,7 +698,7 @@ class ReplicationCacheEntry {
   async load(thread) {
     this.timestamp = Date.now();
     await this.clear();
-    if (thread && cds.context && this.service instanceof SQLiteService) {
+    if (thread && cds.context && this.service instanceof this.cache.SQLiteService) {
       const srcTx = this.service.tx(cds.context);
       await this.db.tx({ tenant: this.tenant.id }, async (destTx) => {
         await this.loadRecords(srcTx, destTx);
@@ -803,7 +804,7 @@ class ReplicationCacheEntry {
 
 module.exports = ReplicationCache;
 
-async function createDB(tenant, model, options) {
+async function createDB(DBService, tenant, model, options) {
   const filePath = await dbPath(tenant, options);
   cds.log(Component).debug("Preparing replication cache database", {
     tenant,
@@ -813,7 +814,7 @@ async function createDB(tenant, model, options) {
     const templateDatabase = await dbPath(Tenant.Template, options);
     await fs.copyFile(templateDatabase, filePath);
   }
-  const db = new SQLiteService(tenant ?? Tenant.Default, model, {
+  const db = new DBService(tenant ?? Tenant.Default, model, {
     kind: "sqlite",
     impl: "@cap-js/sqlite",
     multiTenant: false,