koatty_cacheable 2.0.0 → 2.0.1

package/CHANGELOG.md

@@ -2,13 +2,9 @@
 
 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.
 
-## [2.0.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.6.1...v2.0.0) (2025-06-22)
+### [2.0.1](https://github.com/thinkkoa/koatty_cacheable/compare/v1.6.1...v2.0.1) (2025-11-02)
 
-
-### Features
-
-* enhance cache decorators to support both global and decorator-specific options ([1e70a64](https://github.com/thinkkoa/koatty_cacheable/commit/1e70a64b099e44c8f89180d501899c7e90d83264))
-* implement CacheAble and CacheEvict decorators with unified injection system ([621c02c](https://github.com/thinkkoa/koatty_cacheable/commit/621c02c89596ccca61619ccd603e1868b38b6764))
+## [2.0.0](https://github.com/thinkkoa/koatty_cacheable/compare/v1.6.1...v2.0.0) (2025-11-02)
 
 ### [1.6.1](https://github.com/thinkkoa/koatty_cacheable/compare/v1.6.0...v1.6.1) (2025-06-09)
 

package/README.md

@@ -1,8 +1,8 @@
 # koatty_cacheable
 
-Cacheable plugin for Koatty.
+Cacheable for koatty.
 
-Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别的缓存功能。
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
 
 ## 特性
 
@@ -13,7 +13,6 @@ Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别
 - 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
 - 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
-- 📦 **插件化设计**: 遵循 Koatty 插件标准，统一管理
 
 ## 安装
 
@@ -21,68 +20,74 @@ Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别
 npm install koatty_cacheable
 ```
 
-## 配置
+## 快速开始
 
-### 1. Generate Plugin Template
+### 1. 生成插件模板
 
-Use Koatty CLI to generate the plugin template:
+使用 Koatty CLI 生成插件模板：
 
 ```bash
 kt plugin Cacheable
 ```
 
-Create `src/plugin/Cacheable.ts`:
+创建 `src/plugin/Cacheable.ts`：
 
 ```typescript
 import { Plugin, IPlugin, App } from "koatty";
-import { KoattyCache } from "koatty_cacheable";
+import { KoattyCached } from "koatty_cacheable";
 
 @Plugin()
 export class Cacheable implements IPlugin {
   run(options: any, app: App) {
-    return KoattyCache(options, app);
+    return KoattyCached(options, app);
   }
 }
 ```
 
-### 2. Configure Plugin
+### 2. 配置插件
 
-Update `src/config/plugin.ts`:
+更新 `src/config/plugin.ts`：
 
 ```typescript
 export default {
-  list: ["Cacheable"], // Plugin loading order
+  list: ["Cacheable"], // 插件加载顺序
   config: {
     Cacheable: {
-      cacheTimeout: 300,        // 默认缓存过期时间（秒）
-      delayedDoubleDeletion: true, // 默认启用延迟双删策略
-      redisConfig: {
-        host: "127.0.0.1",
-        port: 6379,
-        password: "",
-        db: 0,
-        keyPrefix: "koatty:cache:"
-      }
+      type: "memory", // 缓存类型: "redis" 或 "memory"，默认为 "memory"
+      db: 0,
+      timeout: 30,
+      // Redis 配置 (当 type 为 "redis" 时)
+      // key_prefix: "koatty",
+      // host: '127.0.0.1',
+      // port: 6379,
+      // name: "",
+      // username: "",
+      // password: "",
+      // pool_size: 10,
+      // conn_timeout: 30
     }
   }
 };
 ```
 
+**注意事项**:
+- 插件会在应用启动时自动初始化缓存
+- 必须在插件配置中提供正确的缓存配置
+- 如果缓存未正确初始化，装饰器方法会直接执行而不进行缓存（优雅降级）
+
 ## 使用方法
 
 ### 基本用法
 
 ```typescript
 import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
-import { Component } from "koatty_container";
 
-@Component()
 export class UserService {
 
     // 自动缓存方法返回值
     @CacheAble("userCache", {
         params: ["id"],    // 使用 id 参数作为缓存键的一部分
-        timeout: 300       // 缓存过期时间（秒），默认使用插件配置的 cacheTimeout
+        timeout: 300       // 缓存过期时间（秒），默认 300 秒
     })
     async getUserById(id: string): Promise<User> {
         // 数据库查询逻辑
@@ -92,7 +97,7 @@ export class UserService {
     // 自动清除相关缓存
     @CacheEvict("userCache", {
         params: ["id"],                    // 使用 id 参数定位要清除的缓存
-        delayedDoubleDeletion: true        // 启用延迟双删策略，默认使用插件配置的 delayedDoubleDeletion
+        delayedDoubleDeletion: true        // 启用延迟双删策略，默认 true
     })
     async updateUser(id: string, userData: Partial<User>): Promise<User> {
         // 更新用户数据
@@ -119,9 +124,6 @@ export class UserService {
 ### 高级用法
 
 ```typescript
-import { Component } from "koatty_container";
-
-@Component()
 export class ProductService {
 
     // 无参数缓存
@@ -133,7 +135,7 @@ export class ProductService {
     // 多参数缓存
     @CacheAble("productSearch", {
         params: ["category", "keyword"],
-        timeout: 600  // 覆盖插件配置的默认时间
+        timeout: 600
     })
     async searchProducts(category: string, keyword: string, page: number = 1): Promise<Product[]> {
         return await this.productRepository.search(category, keyword, page);
@@ -142,7 +144,7 @@ export class ProductService {
     // 立即清除缓存（不使用延迟双删）
     @CacheEvict("productSearch", {
         params: ["category"],
-        delayedDoubleDeletion: false  // 覆盖插件配置的默认策略
+        delayedDoubleDeletion: false
     })
     async updateProductCategory(category: string, updates: any): Promise<void> {
         await this.productRepository.updateCategory(category, updates);
@@ -202,33 +204,14 @@ export class ProductService {
 
 这样可以避免在并发场景下出现脏数据。
 
-## 配置优先级
-
-配置项的优先级从高到低：
-
-1. **装饰器配置**: 直接在 `@CacheAble` 或 `@CacheEvict` 中指定的选项
-2. **插件配置**: 在 `src/config/plugin.ts` 中配置的 `Cacheable` 插件选项
-3. **默认值**: 系统内置的默认配置
-
-例如：
-```typescript
-// 插件配置
-Cacheable: {
-  cacheTimeout: 300,
-  delayedDoubleDeletion: true
-}
-
-// 装饰器配置会覆盖插件配置
-@CacheAble("user", {
-  timeout: 600  // 使用 600 秒而不是插件配置的 300 秒
-})
-```
-
 ## 注意事项
 
-1. 缓存的数据会自动进行 JSON 序列化/反序列化
-2. 如果缓存服务不可用，方法会正常执行，不会抛出错误
-3. 插件会在应用启动时自动注入缓存功能到所有使用装饰器的方法
+1. **初始化顺序**: 必须先调用 `KoattyCached()` 初始化缓存，然后再使用装饰器。建议在应用启动时（如 `init()` 方法中）进行初始化
+2. 装饰器只能用于 `SERVICE` 和 `COMPONENT` 类型的类
+3. 被装饰的方法必须是异步方法（返回 Promise）
+4. 缓存的数据会自动进行 JSON 序列化/反序列化
+5. 如果缓存服务不可用，方法会正常执行，不会抛出错误（优雅降级）
+6. 缓存键长度超过 128 字符时会自动使用 murmur hash 进行压缩
 
 ## 许可证
 

package/dist/README.md

@@ -1,8 +1,8 @@
 # koatty_cacheable
 
-Cacheable plugin for Koatty.
+Cacheable for koatty.
 
-Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别的缓存功能。
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
 
 ## 特性
 
@@ -13,7 +13,6 @@ Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别
 - 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
 - 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
-- 📦 **插件化设计**: 遵循 Koatty 插件标准，统一管理
 
 ## 安装
 
@@ -21,68 +20,74 @@ Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别
 npm install koatty_cacheable
 ```
 
-## 配置
+## 快速开始
 
-### 1. Generate Plugin Template
+### 1. 生成插件模板
 
-Use Koatty CLI to generate the plugin template:
+使用 Koatty CLI 生成插件模板：
 
 ```bash
 kt plugin Cacheable
 ```
 
-Create `src/plugin/Cacheable.ts`:
+创建 `src/plugin/Cacheable.ts`：
 
 ```typescript
 import { Plugin, IPlugin, App } from "koatty";
-import { KoattyCache } from "koatty_cacheable";
+import { KoattyCached } from "koatty_cacheable";
 
 @Plugin()
 export class Cacheable implements IPlugin {
   run(options: any, app: App) {
-    return KoattyCache(options, app);
+    return KoattyCached(options, app);
   }
 }
 ```
 
-### 2. Configure Plugin
+### 2. 配置插件
 
-Update `src/config/plugin.ts`:
+更新 `src/config/plugin.ts`：
 
 ```typescript
 export default {
-  list: ["Cacheable"], // Plugin loading order
+  list: ["Cacheable"], // 插件加载顺序
   config: {
     Cacheable: {
-      cacheTimeout: 300,        // 默认缓存过期时间（秒）
-      delayedDoubleDeletion: true, // 默认启用延迟双删策略
-      redisConfig: {
-        host: "127.0.0.1",
-        port: 6379,
-        password: "",
-        db: 0,
-        keyPrefix: "koatty:cache:"
-      }
+      type: "memory", // 缓存类型: "redis" 或 "memory"，默认为 "memory"
+      db: 0,
+      timeout: 30,
+      // Redis 配置 (当 type 为 "redis" 时)
+      // key_prefix: "koatty",
+      // host: '127.0.0.1',
+      // port: 6379,
+      // name: "",
+      // username: "",
+      // password: "",
+      // pool_size: 10,
+      // conn_timeout: 30
     }
   }
 };
 ```
 
+**注意事项**:
+- 插件会在应用启动时自动初始化缓存
+- 必须在插件配置中提供正确的缓存配置
+- 如果缓存未正确初始化，装饰器方法会直接执行而不进行缓存（优雅降级）
+
 ## 使用方法
 
 ### 基本用法
 
 ```typescript
 import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
-import { Component } from "koatty_container";
 
-@Component()
 export class UserService {
 
     // 自动缓存方法返回值
     @CacheAble("userCache", {
         params: ["id"],    // 使用 id 参数作为缓存键的一部分
-        timeout: 300       // 缓存过期时间（秒），默认使用插件配置的 cacheTimeout
+        timeout: 300       // 缓存过期时间（秒），默认 300 秒
     })
     async getUserById(id: string): Promise<User> {
         // 数据库查询逻辑
@@ -92,7 +97,7 @@ export class UserService {
     // 自动清除相关缓存
     @CacheEvict("userCache", {
         params: ["id"],                    // 使用 id 参数定位要清除的缓存
-        delayedDoubleDeletion: true        // 启用延迟双删策略，默认使用插件配置的 delayedDoubleDeletion
+        delayedDoubleDeletion: true        // 启用延迟双删策略，默认 true
     })
     async updateUser(id: string, userData: Partial<User>): Promise<User> {
         // 更新用户数据
@@ -119,9 +124,6 @@ export class UserService {
 ### 高级用法
 
 ```typescript
-import { Component } from "koatty_container";
-
-@Component()
 export class ProductService {
 
     // 无参数缓存
@@ -133,7 +135,7 @@ export class ProductService {
     // 多参数缓存
     @CacheAble("productSearch", {
         params: ["category", "keyword"],
-        timeout: 600  // 覆盖插件配置的默认时间
+        timeout: 600
     })
     async searchProducts(category: string, keyword: string, page: number = 1): Promise<Product[]> {
         return await this.productRepository.search(category, keyword, page);
@@ -142,7 +144,7 @@ export class ProductService {
     // 立即清除缓存（不使用延迟双删）
     @CacheEvict("productSearch", {
         params: ["category"],
-        delayedDoubleDeletion: false  // 覆盖插件配置的默认策略
+        delayedDoubleDeletion: false
     })
     async updateProductCategory(category: string, updates: any): Promise<void> {
         await this.productRepository.updateCategory(category, updates);
@@ -202,33 +204,14 @@ export class ProductService {
 
 这样可以避免在并发场景下出现脏数据。
 
-## 配置优先级
-
-配置项的优先级从高到低：
-
-1. **装饰器配置**: 直接在 `@CacheAble` 或 `@CacheEvict` 中指定的选项
-2. **插件配置**: 在 `src/config/plugin.ts` 中配置的 `Cacheable` 插件选项
-3. **默认值**: 系统内置的默认配置
-
-例如：
-```typescript
-// 插件配置
-Cacheable: {
-  cacheTimeout: 300,
-  delayedDoubleDeletion: true
-}
-
-// 装饰器配置会覆盖插件配置
-@CacheAble("user", {
-  timeout: 600  // 使用 600 秒而不是插件配置的 300 秒
-})
-```
-
 ## 注意事项
 
-1. 缓存的数据会自动进行 JSON 序列化/反序列化
-2. 如果缓存服务不可用，方法会正常执行，不会抛出错误
-3. 插件会在应用启动时自动注入缓存功能到所有使用装饰器的方法
+1. **初始化顺序**: 必须先调用 `KoattyCached()` 初始化缓存，然后再使用装饰器。建议在应用启动时（如 `init()` 方法中）进行初始化
+2. 装饰器只能用于 `SERVICE` 和 `COMPONENT` 类型的类
+3. 被装饰的方法必须是异步方法（返回 Promise）
+4. 缓存的数据会自动进行 JSON 序列化/反序列化
+5. 如果缓存服务不可用，方法会正常执行，不会抛出错误（优雅降级）
+6. 缓存键长度超过 128 字符时会自动使用 murmur hash 进行压缩
 
 ## 许可证
 

package/dist/index.d.ts

@@ -1,13 +1,13 @@
 /*!
 * @Author: richen
-* @Date: 2025-06-23 01:59:58
+* @Date: 2025-11-02 09:20:03
 * @License: BSD (3-Clause)
 * @Copyright (c) - <richenlin(at)gmail.com>
 * @HomePage: https://koatty.org/
 */
+import { CacheStore } from 'koatty_store';
 import { Koatty } from 'koatty_core';
-
-export declare const CACHE_METADATA_KEY = "CACHE_METADATA_KEY";
+import { StoreOptions } from 'koatty_store';
 
 /**
  * Decorate this method to support caching.
@@ -27,15 +27,15 @@ export declare const CACHE_METADATA_KEY = "CACHE_METADATA_KEY";
  * Use the 'id' parameters of the method as cache subkeys, the cache expiration time 30s
  * @returns {MethodDecorator}
  */
-export declare function CacheAble(cacheNameOrOpt?: string | CacheAbleOpt, opt?: CacheAbleOpt): MethodDecorator;
+export declare function CacheAble(cacheName: string, opt?: CacheAbleOpt): MethodDecorator;
 
 /**
- * @description: CacheAble decorator options
+ * @description:
+ * @return {*}
  */
 export declare interface CacheAbleOpt {
     params?: string[];
     timeout?: number;
-    cacheName?: string;
 }
 
 /**
@@ -54,40 +54,36 @@ export declare interface CacheAbleOpt {
  *  and clear the cache after the method executed
  * @returns
  */
-export declare function CacheEvict(cacheNameOrOpt?: string | CacheEvictOpt, opt?: CacheEvictOpt): MethodDecorator;
+export declare function CacheEvict(cacheName: string, opt?: CacheEvictOpt): (target: any, methodName: string, descriptor: PropertyDescriptor) => PropertyDescriptor;
 
 /**
- * @description: CacheEvict decorator options
+ * @description:
+ * @return {*}
  */
 export declare interface CacheEvictOpt {
     params?: string[];
     delayedDoubleDeletion?: boolean;
-    cacheName?: string;
+    delayTime?: number;
 }
 
-declare interface CacheOptions {
-    cacheTimeout?: number;
-    delayedDoubleDeletion?: boolean;
-    redisConfig?: RedisConfig;
-}
+/**
+ * Close cache store connection for cleanup (mainly for testing)
+ */
+export declare function CloseCacheStore(): Promise<void>;
 
-export declare enum DecoratorType {
-    CACHE_EVICT = "CACHE_EVICT",
-    CACHE_ABLE = "CACHE_ABLE"
-}
+/**
+ * get instances of storeCache
+ *
+ * @export
+ * @param {StoreOptions} options
+ * @returns {*}  {CacheStore}
+ */
+export declare function GetCacheStore(options?: StoreOptions): Promise<CacheStore>;
 
 /**
- * @param options - The options for the scheduled job
+ * @param options - The options for the cached options
  * @param app - The Koatty application instance
  */
-export declare function KoattyCache(options: CacheOptions, app: Koatty): Promise<void>;
-
-declare interface RedisConfig {
-    host?: string;
-    port?: number;
-    password?: string;
-    db?: number;
-    keyPrefix?: string;
-}
+export declare function KoattyCached(options: StoreOptions, app: Koatty): Promise<void>;
 
 export { }