koatty_cacheable 1.5.0 → 1.6.1

package/.rollup.config.js

@@ -3,61 +3,58 @@
  * @Usage: 
  * @Author: richen
  * @Date: 2021-12-17 10:20:44
- * @LastEditTime: 2021-12-18 11:58:46
+ * @LastEditTime: 2024-11-04 22:04:45
  */
+import commonjs from '@rollup/plugin-commonjs';
 import json from "@rollup/plugin-json";
+import resolve from '@rollup/plugin-node-resolve';
+import { builtinModules } from 'module';
+import del from "rollup-plugin-delete";
 import typescript from 'rollup-plugin-typescript2';
 // import babel from '@rollup/plugin-babel';
+const pkg = require('./package.json');
 
 export default [
-    {
-        input: './src/index.ts',
-        output: [{
-            format: 'cjs',
-            file: './dist/index.js',
-            banner: require('./scripts/copyright')
-        }],
-        plugins: [
-            // babel({
-            //     babelHelpers: "runtime",
-            //     configFile: './babel.config.js',
-            //     exclude: 'node_modules/**',
-            // }),
-            json(),
-            typescript({
-                tsconfigOverride: {
-                    compilerOptions: {
-                        declaration: false,
-                        declarationMap: false,
-                        module: "ESNext"
-                    }
-                }
-            })
-        ]
-    },
-    {
-        input: './src/index.ts',
-        output: [{
-            format: 'es',
-            file: './dist/index.mjs',
-            banner: require('./scripts/copyright')
-        }],
-        plugins: [
-            // babel({
-            //     babelHelpers: "runtime",
-            //     configFile: './babel.config.js',
-            //     exclude: 'node_modules/**',
-            // }),
-            json(),
-            typescript({
-                tsconfigOverride: {
-                    compilerOptions: {
-                        declaration: false,
-                        declarationMap: false,
-                        module: "ESNext"
-                    }
-                }
-            })
-        ]
-    }
+  {
+    input: './src/index.ts',
+    output: [
+      {
+        format: 'cjs',
+        file: './dist/index.js',
+        banner: require('./scripts/copyright'),
+      },
+      {
+        format: 'es',
+        file: './dist/index.mjs',
+        banner: require('./scripts/copyright'),
+      },
+    ],
+    plugins: [
+      del({ targets: ["dist/*", "temp/*", "docs/api"] }),
+      // babel({
+      //     babelHelpers: "runtime",
+      //     configFile: './babel.config.js',
+      //     exclude: 'node_modules/**',
+      // }),
+      json(),
+      resolve({
+        preferBuiltins: true, // 优先选择内置模块
+      }),
+      commonjs(),
+      typescript({
+        tsconfigOverride: {
+          compilerOptions: {
+            declaration: false,
+            declarationMap: false,
+            module: "ESNext"
+          }
+        }
+      })
+    ],
+    external: [
+      ...builtinModules, // 排除 Node.js 内置模块
+      ...Object.keys(pkg.dependencies || {}), // 排除 package.json 中的外部依赖
+    ],
+  },
+
 ]

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.6.1](https://github.com/thinkkoa/koatty_cacheable/compare/v1.6.0...v1.6.1) (2025-06-09)
+
+## [1.6.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.5.0...v1.6.0) (2024-11-07)
+
 ## [1.5.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.3...v1.5.0) (2024-04-01)
 
 

package/README.md

@@ -1,19 +1,36 @@
 # koatty_cacheable
+
 Cacheable for koatty.
 
-Koatty框架的 CacheAble, Cacheable, CacheEvict 支持库
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
+
+## 特性
+
+- 🚀 **简单易用**: 通过装饰器轻松添加缓存功能
+- 🔄 **自动缓存**: `@CacheAble` 装饰器自动缓存方法返回值
+- 🗑️ **智能清除**: `@CacheEvict` 装饰器智能清除相关缓存
+- ⚡ **延迟双删**: 支持延迟双删策略，解决缓存一致性问题
+- 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
+- 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
+- 🛡️ **类型安全**: 完整的 TypeScript 支持
 
+## 安装
 
-# Usage
+```bash
+npm install koatty_cacheable
+```
+
+## 配置
 
-db.ts in koatty project:
+在 koatty 项目的 `db.ts` 配置文件中添加缓存配置：
 
-```js
+```typescript
 export default {
-    ...
+    // ... 其他配置
 
     "CacheStore": {
-        type: "memory", // redis or memory, memory is default
+        type: "memory", // 缓存类型: "redis" 或 "memory"，默认为 "memory"
+        // Redis 配置 (当 type 为 "redis" 时)
         // key_prefix: "koatty",
         // host: '127.0.0.1',
         // port: 6379,
@@ -26,32 +43,146 @@ export default {
         // conn_timeout: 30
     },
 
-    ...
+    // ... 其他配置
 };
-
 ```
 
-used in service: 
+## 使用方法
 
-```js
+### 基本用法
+
+```typescript
 import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
 
-export class TestService {
+export class UserService {
 
-    @CacheAble("testCache") // auto cached
-    getTest(){
-        //todo
+    // 自动缓存方法返回值
+    @CacheAble("userCache", {
+        params: ["id"],    // 使用 id 参数作为缓存键的一部分
+        timeout: 300       // 缓存过期时间（秒），默认 300 秒
+    })
+    async getUserById(id: string): Promise<User> {
+        // 数据库查询逻辑
+        return await this.userRepository.findById(id);
     }
 
-    @CacheEvict("testCache") // auto clear cache
-    setTest(){
-        //todo
+    // 自动清除相关缓存
+    @CacheEvict("userCache", {
+        params: ["id"],                    // 使用 id 参数定位要清除的缓存
+        delayedDoubleDeletion: true        // 启用延迟双删策略，默认 true
+    })
+    async updateUser(id: string, userData: Partial<User>): Promise<User> {
+        // 更新用户数据
+        const updatedUser = await this.userRepository.update(id, userData);
+        return updatedUser;
     }
 
-    test(){
-        const store = GetCacheStore(this.app);
-        store.set(key, value);
+    // 手动操作缓存
+    async customCacheOperation() {
+        const store = await GetCacheStore(this.app);
+        
+        // 设置缓存
+        await store.set("custom:key", "value", 60);
+        
+        // 获取缓存
+        const value = await store.get("custom:key");
+        
+        // 删除缓存
+        await store.del("custom:key");
     }
 }
+```
+
+### 高级用法
+
+```typescript
+export class ProductService {
+
+    // 无参数缓存
+    @CacheAble("productStats")
+    async getProductStats(): Promise<ProductStats> {
+        return await this.calculateStats();
+    }
+
+    // 多参数缓存
+    @CacheAble("productSearch", {
+        params: ["category", "keyword"],
+        timeout: 600
+    })
+    async searchProducts(category: string, keyword: string, page: number = 1): Promise<Product[]> {
+        return await this.productRepository.search(category, keyword, page);
+    }
+
+    // 立即清除缓存（不使用延迟双删）
+    @CacheEvict("productSearch", {
+        params: ["category"],
+        delayedDoubleDeletion: false
+    })
+    async updateProductCategory(category: string, updates: any): Promise<void> {
+        await this.productRepository.updateCategory(category, updates);
+    }
+}
+```
+
+## API 文档
+
+### @CacheAble(cacheName, options?)
+
+自动缓存装饰器，缓存方法的返回值。
+
+**参数:**
+- `cacheName: string` - 缓存名称
+- `options?: CacheAbleOpt` - 缓存选项
+  - `params?: string[]` - 用作缓存键的参数名数组
+  - `timeout?: number` - 缓存过期时间（秒），默认 300
+
+### @CacheEvict(cacheName, options?)
+
+自动清除缓存装饰器，在方法执行后清除相关缓存。
+
+**参数:**
+- `cacheName: string` - 要清除的缓存名称
+- `options?: CacheEvictOpt` - 清除选项
+  - `params?: string[]` - 用于定位缓存的参数名数组
+  - `delayedDoubleDeletion?: boolean` - 是否启用延迟双删策略，默认 true
+
+### GetCacheStore(app?)
+
+获取缓存存储实例。
+
+**参数:**
+- `app?: Application` - Koatty 应用实例
+
+**返回:** `Promise<CacheStore>`
+
+## 缓存键生成规则
+
+缓存键按以下格式生成：
+```
+{cacheName}:{paramName1}:{paramValue1}:{paramName2}:{paramValue2}...
+```
+
+例如：
+- `@CacheAble("user", {params: ["id"]})` + `getUserById("123")` → `user:id:123`
+- 当缓存键长度超过 128 字符时，会自动使用 murmur hash 进行压缩
+
+## 延迟双删策略
+
+延迟双删是一种解决缓存一致性问题的策略：
+
+1. 立即删除缓存
+2. 执行数据更新操作
+3. 延迟 5 秒后再次删除缓存
+
+这样可以避免在并发场景下出现脏数据。
+
+## 注意事项
+
+1. 装饰器只能用于 `SERVICE` 和 `COMPONENT` 类型的类
+2. 被装饰的方法必须是异步方法（返回 Promise）
+3. 缓存的数据会自动进行 JSON 序列化/反序列化
+4. 如果缓存服务不可用，方法会正常执行，不会抛出错误
+
+## 许可证
 
-```
+BSD-3-Clause

package/dist/README.md

@@ -1,19 +1,36 @@
 # koatty_cacheable
+
 Cacheable for koatty.
 
-Koatty框架的 CacheAble, Cacheable, CacheEvict 支持库
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
+
+## 特性
+
+- 🚀 **简单易用**: 通过装饰器轻松添加缓存功能
+- 🔄 **自动缓存**: `@CacheAble` 装饰器自动缓存方法返回值
+- 🗑️ **智能清除**: `@CacheEvict` 装饰器智能清除相关缓存
+- ⚡ **延迟双删**: 支持延迟双删策略，解决缓存一致性问题
+- 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
+- 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
+- 🛡️ **类型安全**: 完整的 TypeScript 支持
 
+## 安装
 
-# Usage
+```bash
+npm install koatty_cacheable
+```
+
+## 配置
 
-db.ts in koatty project:
+在 koatty 项目的 `db.ts` 配置文件中添加缓存配置：
 
-```js
+```typescript
 export default {
-    ...
+    // ... 其他配置
 
     "CacheStore": {
-        type: "memory", // redis or memory, memory is default
+        type: "memory", // 缓存类型: "redis" 或 "memory"，默认为 "memory"
+        // Redis 配置 (当 type 为 "redis" 时)
         // key_prefix: "koatty",
         // host: '127.0.0.1',
         // port: 6379,
@@ -26,32 +43,146 @@ export default {
         // conn_timeout: 30
     },
 
-    ...
+    // ... 其他配置
 };
-
 ```
 
-used in service: 
+## 使用方法
 
-```js
+### 基本用法
+
+```typescript
 import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
 
-export class TestService {
+export class UserService {
 
-    @CacheAble("testCache") // auto cached
-    getTest(){
-        //todo
+    // 自动缓存方法返回值
+    @CacheAble("userCache", {
+        params: ["id"],    // 使用 id 参数作为缓存键的一部分
+        timeout: 300       // 缓存过期时间（秒），默认 300 秒
+    })
+    async getUserById(id: string): Promise<User> {
+        // 数据库查询逻辑
+        return await this.userRepository.findById(id);
     }
 
-    @CacheEvict("testCache") // auto clear cache
-    setTest(){
-        //todo
+    // 自动清除相关缓存
+    @CacheEvict("userCache", {
+        params: ["id"],                    // 使用 id 参数定位要清除的缓存
+        delayedDoubleDeletion: true        // 启用延迟双删策略，默认 true
+    })
+    async updateUser(id: string, userData: Partial<User>): Promise<User> {
+        // 更新用户数据
+        const updatedUser = await this.userRepository.update(id, userData);
+        return updatedUser;
     }
 
-    test(){
-        const store = GetCacheStore(this.app);
-        store.set(key, value);
+    // 手动操作缓存
+    async customCacheOperation() {
+        const store = await GetCacheStore(this.app);
+        
+        // 设置缓存
+        await store.set("custom:key", "value", 60);
+        
+        // 获取缓存
+        const value = await store.get("custom:key");
+        
+        // 删除缓存
+        await store.del("custom:key");
     }
 }
+```
+
+### 高级用法
+
+```typescript
+export class ProductService {
+
+    // 无参数缓存
+    @CacheAble("productStats")
+    async getProductStats(): Promise<ProductStats> {
+        return await this.calculateStats();
+    }
+
+    // 多参数缓存
+    @CacheAble("productSearch", {
+        params: ["category", "keyword"],
+        timeout: 600
+    })
+    async searchProducts(category: string, keyword: string, page: number = 1): Promise<Product[]> {
+        return await this.productRepository.search(category, keyword, page);
+    }
+
+    // 立即清除缓存（不使用延迟双删）
+    @CacheEvict("productSearch", {
+        params: ["category"],
+        delayedDoubleDeletion: false
+    })
+    async updateProductCategory(category: string, updates: any): Promise<void> {
+        await this.productRepository.updateCategory(category, updates);
+    }
+}
+```
+
+## API 文档
+
+### @CacheAble(cacheName, options?)
+
+自动缓存装饰器，缓存方法的返回值。
+
+**参数:**
+- `cacheName: string` - 缓存名称
+- `options?: CacheAbleOpt` - 缓存选项
+  - `params?: string[]` - 用作缓存键的参数名数组
+  - `timeout?: number` - 缓存过期时间（秒），默认 300
+
+### @CacheEvict(cacheName, options?)
+
+自动清除缓存装饰器，在方法执行后清除相关缓存。
+
+**参数:**
+- `cacheName: string` - 要清除的缓存名称
+- `options?: CacheEvictOpt` - 清除选项
+  - `params?: string[]` - 用于定位缓存的参数名数组
+  - `delayedDoubleDeletion?: boolean` - 是否启用延迟双删策略，默认 true
+
+### GetCacheStore(app?)
+
+获取缓存存储实例。
+
+**参数:**
+- `app?: Application` - Koatty 应用实例
+
+**返回:** `Promise<CacheStore>`
+
+## 缓存键生成规则
+
+缓存键按以下格式生成：
+```
+{cacheName}:{paramName1}:{paramValue1}:{paramName2}:{paramValue2}...
+```
+
+例如：
+- `@CacheAble("user", {params: ["id"]})` + `getUserById("123")` → `user:id:123`
+- 当缓存键长度超过 128 字符时，会自动使用 murmur hash 进行压缩
+
+## 延迟双删策略
+
+延迟双删是一种解决缓存一致性问题的策略：
+
+1. 立即删除缓存
+2. 执行数据更新操作
+3. 延迟 5 秒后再次删除缓存
+
+这样可以避免在并发场景下出现脏数据。
+
+## 注意事项
+
+1. 装饰器只能用于 `SERVICE` 和 `COMPONENT` 类型的类
+2. 被装饰的方法必须是异步方法（返回 Promise）
+3. 缓存的数据会自动进行 JSON 序列化/反序列化
+4. 如果缓存服务不可用，方法会正常执行，不会抛出错误
+
+## 许可证
 
-```
+BSD-3-Clause

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 /*!
 * @Author: richen
-* @Date: 2024-04-01 15:47:51
+* @Date: 2025-06-09 13:04:42
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
@@ -64,6 +64,11 @@ export declare interface CacheEvictOpt {
     delayedDoubleDeletion?: boolean;
 }
 
+/**
+ * Close cache store connection for cleanup (mainly for testing)
+ */
+export declare function CloseCacheStore(): Promise<void>;
+
 /**
  * get instances of storeCache
  *
@@ -71,6 +76,12 @@ export declare interface CacheEvictOpt {
  * @param {Application} app
  * @returns {*}  {CacheStore}
  */
-export declare function GetCacheStore(app: Application): Promise<CacheStore>;
+export declare function GetCacheStore(app?: Application): Promise<CacheStore>;
+
+/**
+ * initiation CacheStore connection and client.
+ *
+ */
+export declare function InitCacheStore(): Promise<void>;
 
 export { }