@abtnode/db-cache 1.16.45-beta-20250609-111118-0d252ebe → 1.16.45-beta-20250610-112229-2eb0face

package/README.md

@@ -2,17 +2,21 @@
 
 Use Redis or Sqlite3 LRC cache, multithread safe
 
-约定: DB Cache 不能作为数据的单一来源, 我们要假定 Cache 的数据随时可能被释放来进行业务开发.
-不限制 cache 个数: Redis 我们约定直接在 redis 配置好最大内存和达到内存上限时自动移除旧的; Sqlite 由于使用的是硬盘, 也没有必要限制上限.
+**Convention:** DB Cache must not be the sole source of truth. We must assume that cache data can be released at any time during development.
 
-约定 Redis 启动配置:
+**No limit on the number of caches:**
 
-- 确保 redis 仅在内网
-- 不做持久化
-- 最大只用 512MB 内存
-- 内存满时对所有键做 LRU (最近最久未使用) 淘汰
+For Redis, we configure it with a max memory limit and enable automatic LRU (Least Recently Used) eviction when full.  
+For SQLite, since it's disk-based, there's no need to limit the size.
 
-```
+## Redis Startup Configuration
+
+- Redis bound to the internal network only
+- No persistence
+- Max memory: 512MB
+- Eviction policy: allkeys-lru (LRU for all keys)
+
+```bash
 docker run -d \
   --name db-cache-redis \
   -p 127.0.0.1:40409:6379 \
@@ -26,7 +30,7 @@ docker run -d \
 
 ## Usage
 
-```shell
+```bash
 yarn add @abtnode/db-cache
 ```
 
@@ -35,7 +39,7 @@ Then:
 ```javascript
 const { DBCache } = require('@abtnode/db-cache');
 
-// 当第一次使用时, 才会去读取配置
+// Configuration will only be read on first use
 const dbCache = new DBCache(() => ({
   prefix: 'the prefix key',
   ttl: 60 * 1000,
@@ -50,7 +54,7 @@ await dbCache.delete('key');
 await dbCache.has('key');
 ```
 
-## hash set/get 的使用
+## Group set/get usage
 
 ```javascript
 const cache = new DBCache(() => ({
@@ -63,41 +67,61 @@ const cache = new DBCache(() => ({
 await cache.groupSet('group-key', 'sub-key', { a: 'b' });
 const data = await cache.groupGet('group-key', 'sub-key');
 await cache.groupDel('group-key', 'sub-key');
-await cache.del('group-key'); // delete group all key
+await cache.del('group-key'); // delete all keys under the group
 ```
 
-## 锁的使用
+## Auto Cache
+
+`autoCache` or `autoCacheGroup`:
+
+If the value is cached, return it; otherwise, compute and cache it
+
+Errors during computation won't be cached
 
 ```javascript
-const lock = new DBCache(() => ({
+const cache = new DBCache(() => ({
   prefix: 'the prefix key',
   ttl: 5 * 1000,
   sqlitePath: 'test.db',
   redisURL: process.env.REDIS_URL,
 }));
-await lock.acquire('key name');
-// do something
-await lock.releaseLock('key name');
 
-// or wait ttl, auto release lock
+await cache.autoCache('key', async () => {
+  return 'want to cache data';
+});
+
+await cache.autoCacheGroup('group-key', 'sub-key', async () => {
+  return 'want to cache data';
+});
 ```
 
-## SQLite 性能
+## Lock usage
 
-默认设置压测性能很低,
+```javascript
+const lock = new DBCache(() => ({
+  prefix: 'the prefix key',
+  ttl: 5 * 1000,
+  sqlitePath: 'test.db',
+  redisURL: process.env.REDIS_URL,
+}));
 
-多线程测试安全, 但是并发非常慢, 放弃所有安全性 (不适合)
+await lock.acquire('key name');
+// do something or wait for TTL to auto-release the lock
+await lock.releaseLock('key name');
+```
 
-使用 WAL (最后使用的方案)
+## SQLite Performance
 
-```
-PRAGMA journal_mode = WAL;          -- 写前日志并行读写
-PRAGMA synchronous = OFF;           -- 放弃每次 fsync，追求速度
-PRAGMA busy_timeout = 10000;       -- 锁冲突时最多等 10 秒
-PRAGMA wal_autocheckpoint = 2000;   -- 每 2000 次写后自动做一次 checkpoint
+**SQLite auto set WAL mode**
+
+```sql
+PRAGMA journal_mode = WAL;          -- Enable Write-Ahead Logging for parallel reads/writes
+PRAGMA synchronous = OFF;           -- Skip fsync for performance
+PRAGMA busy_timeout = 10000;        -- Wait up to 10 seconds on lock conflict
+PRAGMA wal_autocheckpoint = 2000;   -- Auto-checkpoint after every 2000 writes
 ```
 
-压测结果:
+### Benchmark Results
 
 ```
 === SQLite Backend Benchmark ===
@@ -109,27 +133,28 @@ SET  50000 ops in 0.14s -> 370370 ops/sec
 GET  50000 ops in 0.14s -> 349650 ops/sec
 ```
 
-磁盘或硬盘开销:
+### Disk or Memory Usage
 
-```
+Example with 100,000 entries. Sample data:
 
-10w 条数据, 数据样本:
+```json
 {
-    idx: i,
-    v: `value-${i}`,
-    other: `other-${i}`,
-    other2: `other2-${i}`,
-    other3: `other3-${i}`,
-    other4: `other4-${i}`,
-    other5: `other5-${i}`,
-    other6: `other6-${i}`,
-    other7: `other7-${i}`,
-    other8: `other8-${i}`,
-    other9: `other9-${i}`,
-    other10: `other10-${i}`,
-  }
-
+  idx: i,
+  v: `value-${i}`,
+  other: `other-${i}`,
+  other2: `other2-${i}`,
+  other3: `other3-${i}`,
+  other4: `other4-${i}`,
+  other5: `other5-${i}`,
+  other6: `other6-${i}`,
+  other7: `other7-${i}`,
+  other8: `other8-${i}`,
+  other9: `other9-${i}`,
+  other10: `other10-${i}`,
+}
+```
 
+```
 === Redis Memory Info ===
 # Memory
 used_memory_rss_human:57.41M
@@ -137,17 +162,18 @@ used_memory_rss_human:57.41M
 SQLite file size: 31.63 MB
 ```
 
-并发测试是安全的, 取决于 busy_timeout 的时长和并发数
+Concurrency is safe and depends on `busy_timeout` and the level of concurrency.
 
-结论, Redis 大概会是 SQLite 的 20-40 倍性能, 但是 SQLite 不会成为业务的 QPS 瓶颈. SQLite 可以在 RPS 要求不是这么高的情况下, 用硬盘换内存, 还是挺划算的.
+**Conclusion:** Redis is roughly 20–40x faster than SQLite. However, SQLite will not be the QPS bottleneck in most business use cases. It's a cost-effective choice for trading disk space for memory in scenarios with moderate RPS demands.
 
-#### group 实现差异
+---
 
-group 在 redis 使用 hash set 数据结构, 性能差异较小
+### Group Implementation Differences
 
-sqlite group 相当于使用两个 key 进行查询, 性能也很不错
+- Redis: groups are implemented via hash sets — performance is very good.
+- SQLite: implemented with dual-key lookups — still performs well.
 
-下面是 group set/get 的性能:
+**Group set/get performance:**
 
 ```
 === SQLite Backend Benchmark ===
@@ -159,12 +185,15 @@ SET  50000 ops in 0.22s -> 230415 ops/sec
 GET  50000 ops in 0.08s -> 649351 ops/sec
 ```
 
-#### CI 测试 redis
+---
 
-有 TEST_REDIS_URL 环境变量就测试 Redis 模式, 没有就测试 SQLite 模式
+### CI Redis Testing
 
-例子:
+If the `TEST_REDIS_URL` environment variable is set, tests will run in Redis mode.  
+If not, tests will fall back to SQLite mode.
 
-```
+Example:
+
+```bash
 TEST_REDIS_URL="redis://:the_password@127.0.0.1:6379"
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abtnode/db-cache",
-  "version": "1.16.45-beta-20250609-111118-0d252ebe",
+  "version": "1.16.45-beta-20250610-112229-2eb0face",
   "description": "Db cache use redis or sqlite as backend",
   "publishConfig": {
     "access": "public"
@@ -44,5 +44,5 @@
     "typescript": "^5.6.3",
     "unbuild": "^2.0.0"
   },
-  "gitHead": "3ea8ca1f5debfddd15b172c9dd9f4d4eaf22db0e"
+  "gitHead": "d35fb6c907c29f4466fa965c079e1662dc77e582"
 }