koatty_cacheable 1.6.0 → 1.6.1

package/.rollup.config.js

@@ -1,60 +1,60 @@
-/*
- * @Description: 
- * @Usage: 
- * @Author: richen
- * @Date: 2021-12-17 10:20:44
- * @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'),
-      },
-      {
-        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 中的外部依赖
-    ],
-  },
-
+/*
+ * @Description: 
+ * @Usage: 
+ * @Author: richen
+ * @Date: 2021-12-17 10:20:44
+ * @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'),
+      },
+      {
+        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,42 +2,44 @@
 
 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)
-
-
-### Features
-
-* delayedDoubleDeletion ([532f735](https://github.com/thinkkoa/koatty_cacheable/commit/532f735818fc66fa144023cd24282efe350833ba))
-
-### [1.4.3](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.2...v1.4.3) (2024-01-17)
-
-
-### Bug Fixes
-
-* 缓存key拼装 ([5d0b924](https://github.com/thinkkoa/koatty_cacheable/commit/5d0b9248064d353046bd7287d3a3ee5229e88c23))
-
-### [1.4.2](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.1...v1.4.2) (2023-12-20)
-
-### [1.4.1](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.0...v1.4.1) (2023-08-04)
-
-
-### Bug Fixes
-
-* default value ([38f2e57](https://github.com/thinkkoa/koatty_cacheable/commit/38f2e57d52d13482907ca9eac6006d1e841bdadd))
-* 初始化缓存改为appReady执行 ([7e9b1ab](https://github.com/thinkkoa/koatty_cacheable/commit/7e9b1abe6acdbdf1b6ad34efa053cbaca1e7b6d7))
-
-## [1.4.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.3.8...v1.4.0) (2023-02-18)
-
-
-### Bug Fixes
-
-* cache subkey ([408e3c7](https://github.com/thinkkoa/koatty_cacheable/commit/408e3c709a4dfff6e7d224a22d26e58854a805ac))
-* 启动时链接 ([e7ec709](https://github.com/thinkkoa/koatty_cacheable/commit/e7ec7094be106e4e48783c9b214b8369e8a18297))
-* 支持引入变量做缓存key ([4ce81aa](https://github.com/thinkkoa/koatty_cacheable/commit/4ce81aaaf9610f4a62ddf43e3c4389dd003c2db8))
-* 获取单例 ([0759972](https://github.com/thinkkoa/koatty_cacheable/commit/0759972adf7e86312f60f0bf77604bddf06ce0de))
-
-### [1.3.8](https://github.com/thinkkoa/koatty_cacheable/compare/v1.3.6...v1.3.8) (2023-01-13)
-
-### [1.3.7](https://github.com/thinkkoa/koatty_cacheable/compare/v1.3.6...v1.3.7) (2022-05-27)
+## [1.5.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.3...v1.5.0) (2024-04-01)
+
+
+### Features
+
+* delayedDoubleDeletion ([532f735](https://github.com/thinkkoa/koatty_cacheable/commit/532f735818fc66fa144023cd24282efe350833ba))
+
+### [1.4.3](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.2...v1.4.3) (2024-01-17)
+
+
+### Bug Fixes
+
+* 缓存key拼装 ([5d0b924](https://github.com/thinkkoa/koatty_cacheable/commit/5d0b9248064d353046bd7287d3a3ee5229e88c23))
+
+### [1.4.2](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.1...v1.4.2) (2023-12-20)
+
+### [1.4.1](https://github.com/thinkkoa/koatty_cacheable/compare/v1.4.0...v1.4.1) (2023-08-04)
+
+
+### Bug Fixes
+
+* default value ([38f2e57](https://github.com/thinkkoa/koatty_cacheable/commit/38f2e57d52d13482907ca9eac6006d1e841bdadd))
+* 初始化缓存改为appReady执行 ([7e9b1ab](https://github.com/thinkkoa/koatty_cacheable/commit/7e9b1abe6acdbdf1b6ad34efa053cbaca1e7b6d7))
+
+## [1.4.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.3.8...v1.4.0) (2023-02-18)
+
+
+### Bug Fixes
+
+* cache subkey ([408e3c7](https://github.com/thinkkoa/koatty_cacheable/commit/408e3c709a4dfff6e7d224a22d26e58854a805ac))
+* 启动时链接 ([e7ec709](https://github.com/thinkkoa/koatty_cacheable/commit/e7ec7094be106e4e48783c9b214b8369e8a18297))
+* 支持引入变量做缓存key ([4ce81aa](https://github.com/thinkkoa/koatty_cacheable/commit/4ce81aaaf9610f4a62ddf43e3c4389dd003c2db8))
+* 获取单例 ([0759972](https://github.com/thinkkoa/koatty_cacheable/commit/0759972adf7e86312f60f0bf77604bddf06ce0de))
+
+### [1.3.8](https://github.com/thinkkoa/koatty_cacheable/compare/v1.3.6...v1.3.8) (2023-01-13)
+
+### [1.3.7](https://github.com/thinkkoa/koatty_cacheable/compare/v1.3.6...v1.3.7) (2022-05-27)

package/LICENSE

@@ -1,29 +1,29 @@
-BSD 3-Clause License
-
-Copyright (c) 2020, Koatty
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+BSD 3-Clause License
+
+Copyright (c) 2020, Koatty
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.md

@@ -1,57 +1,188 @@
-# koatty_cacheable
-Cacheable for koatty.
-
-Koatty框架的 CacheAble, Cacheable, CacheEvict 支持库
-
-
-# Usage
-
-db.ts in koatty project:
-
-```js
-export default {
-    ...
-
-    "CacheStore": {
-        type: "memory", // redis or memory, memory is default
-        // key_prefix: "koatty",
-        // host: '127.0.0.1',
-        // port: 6379,
-        // name: "",
-        // username: "",
-        // password: "",
-        // db: 0,
-        // timeout: 30,
-        // pool_size: 10,
-        // conn_timeout: 30
-    },
-
-    ...
-};
-
-```
-
-used in service: 
-
-```js
-import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
-
-export class TestService {
-
-    @CacheAble("testCache") // auto cached
-    getTest(){
-        //todo
-    }
-
-    @CacheEvict("testCache") // auto clear cache
-    setTest(){
-        //todo
-    }
-
-    test(){
-        const store = GetCacheStore(this.app);
-        store.set(key, value);
-    }
-}
-
-```
+# koatty_cacheable
+
+Cacheable for koatty.
+
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
+
+## 特性
+
+- 🚀 **简单易用**: 通过装饰器轻松添加缓存功能
+- 🔄 **自动缓存**: `@CacheAble` 装饰器自动缓存方法返回值
+- 🗑️ **智能清除**: `@CacheEvict` 装饰器智能清除相关缓存
+- ⚡ **延迟双删**: 支持延迟双删策略，解决缓存一致性问题
+- 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
+- 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
+- 🛡️ **类型安全**: 完整的 TypeScript 支持
+
+## 安装
+
+```bash
+npm install koatty_cacheable
+```
+
+## 配置
+
+在 koatty 项目的 `db.ts` 配置文件中添加缓存配置：
+
+```typescript
+export default {
+    // ... 其他配置
+
+    "CacheStore": {
+        type: "memory", // 缓存类型: "redis" 或 "memory"，默认为 "memory"
+        // Redis 配置 (当 type 为 "redis" 时)
+        // key_prefix: "koatty",
+        // host: '127.0.0.1',
+        // port: 6379,
+        // name: "",
+        // username: "",
+        // password: "",
+        // db: 0,
+        // timeout: 30,
+        // pool_size: 10,
+        // conn_timeout: 30
+    },
+
+    // ... 其他配置
+};
+```
+
+## 使用方法
+
+### 基本用法
+
+```typescript
+import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
+
+export class UserService {
+
+    // 自动缓存方法返回值
+    @CacheAble("userCache", {
+        params: ["id"],    // 使用 id 参数作为缓存键的一部分
+        timeout: 300       // 缓存过期时间（秒），默认 300 秒
+    })
+    async getUserById(id: string): Promise<User> {
+        // 数据库查询逻辑
+        return await this.userRepository.findById(id);
+    }
+
+    // 自动清除相关缓存
+    @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;
+    }
+
+    // 手动操作缓存
+    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/LICENSE

@@ -1,29 +1,29 @@
-BSD 3-Clause License
-
-Copyright (c) 2020, Koatty
-All rights reserved.
-
-Redistribution and use in source and binary forms, with or without
-modification, are permitted provided that the following conditions are met:
-
-1. Redistributions of source code must retain the above copyright notice, this
-   list of conditions and the following disclaimer.
-
-2. Redistributions in binary form must reproduce the above copyright notice,
-   this list of conditions and the following disclaimer in the documentation
-   and/or other materials provided with the distribution.
-
-3. Neither the name of the copyright holder nor the names of its
-   contributors may be used to endorse or promote products derived from
-   this software without specific prior written permission.
-
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
-AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
-IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
-DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
-FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
-DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
-SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
-CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
-OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+BSD 3-Clause License
+
+Copyright (c) 2020, Koatty
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.