koatty_cacheable 1.6.1 → 2.0.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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)
+
+
+### 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))
+
 ### [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)

package/README.md

@@ -1,8 +1,8 @@
 # koatty_cacheable
 
-Cacheable for koatty.
+Cacheable plugin for Koatty.
 
-Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别的缓存功能。
 
 ## 特性
 
@@ -13,6 +13,7 @@ Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级
 - 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
 - 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
+- 📦 **插件化设计**: 遵循 Koatty 插件标准，统一管理
 
 ## 安装
 
@@ -22,28 +23,48 @@ npm install koatty_cacheable
 
 ## 配置
 
-在 koatty 项目的 `db.ts` 配置文件中添加缓存配置：
+### 1. Generate Plugin Template
+
+Use Koatty CLI to generate the plugin template:
+
+```bash
+kt plugin Cacheable
+```
+
+Create `src/plugin/Cacheable.ts`:
+
+```typescript
+import { Plugin, IPlugin, App } from "koatty";
+import { KoattyCache } from "koatty_cacheable";
+
+@Plugin()
+export class Cacheable implements IPlugin {
+  run(options: any, app: App) {
+    return KoattyCache(options, app);
+  }
+}
+```
+
+### 2. Configure Plugin
+
+Update `src/config/plugin.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
-    },
-
-    // ... 其他配置
+  list: ["Cacheable"], // Plugin loading order
+  config: {
+    Cacheable: {
+      cacheTimeout: 300,        // 默认缓存过期时间（秒）
+      delayedDoubleDeletion: true, // 默认启用延迟双删策略
+      redisConfig: {
+        host: "127.0.0.1",
+        port: 6379,
+        password: "",
+        db: 0,
+        keyPrefix: "koatty:cache:"
+      }
+    }
+  }
 };
 ```
 
@@ -53,13 +74,15 @@ export default {
 
 ```typescript
 import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
+import { Component } from "koatty_container";
 
+@Component()
 export class UserService {
 
     // 自动缓存方法返回值
     @CacheAble("userCache", {
         params: ["id"],    // 使用 id 参数作为缓存键的一部分
-        timeout: 300       // 缓存过期时间（秒），默认 300 秒
+        timeout: 300       // 缓存过期时间（秒），默认使用插件配置的 cacheTimeout
     })
     async getUserById(id: string): Promise<User> {
         // 数据库查询逻辑
@@ -69,7 +92,7 @@ export class UserService {
     // 自动清除相关缓存
     @CacheEvict("userCache", {
         params: ["id"],                    // 使用 id 参数定位要清除的缓存
-        delayedDoubleDeletion: true        // 启用延迟双删策略，默认 true
+        delayedDoubleDeletion: true        // 启用延迟双删策略，默认使用插件配置的 delayedDoubleDeletion
     })
     async updateUser(id: string, userData: Partial<User>): Promise<User> {
         // 更新用户数据
@@ -96,6 +119,9 @@ export class UserService {
 ### 高级用法
 
 ```typescript
+import { Component } from "koatty_container";
+
+@Component()
 export class ProductService {
 
     // 无参数缓存
@@ -107,7 +133,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);
@@ -116,7 +142,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);
@@ -176,12 +202,33 @@ 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. 装饰器只能用于 `SERVICE` 和 `COMPONENT` 类型的类
-2. 被装饰的方法必须是异步方法（返回 Promise）
-3. 缓存的数据会自动进行 JSON 序列化/反序列化
-4. 如果缓存服务不可用，方法会正常执行，不会抛出错误
+1. 缓存的数据会自动进行 JSON 序列化/反序列化
+2. 如果缓存服务不可用，方法会正常执行，不会抛出错误
+3. 插件会在应用启动时自动注入缓存功能到所有使用装饰器的方法
 
 ## 许可证
 

package/dist/README.md

@@ -1,8 +1,8 @@
 # koatty_cacheable
 
-Cacheable for koatty.
+Cacheable plugin for Koatty.
 
-Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级别的缓存功能。
+Koatty框架的 CacheAble, CacheEvict 缓存装饰器插件，提供方法级别的缓存功能。
 
 ## 特性
 
@@ -13,6 +13,7 @@ Koatty框架的 CacheAble, CacheEvict 缓存装饰器支持库，提供方法级
 - 🔧 **多后端支持**: 支持 Memory 和 Redis 缓存后端
 - 🎯 **参数化缓存**: 支持基于方法参数的缓存键生成
 - 🛡️ **类型安全**: 完整的 TypeScript 支持
+- 📦 **插件化设计**: 遵循 Koatty 插件标准，统一管理
 
 ## 安装
 
@@ -22,28 +23,48 @@ npm install koatty_cacheable
 
 ## 配置
 
-在 koatty 项目的 `db.ts` 配置文件中添加缓存配置：
+### 1. Generate Plugin Template
+
+Use Koatty CLI to generate the plugin template:
+
+```bash
+kt plugin Cacheable
+```
+
+Create `src/plugin/Cacheable.ts`:
+
+```typescript
+import { Plugin, IPlugin, App } from "koatty";
+import { KoattyCache } from "koatty_cacheable";
+
+@Plugin()
+export class Cacheable implements IPlugin {
+  run(options: any, app: App) {
+    return KoattyCache(options, app);
+  }
+}
+```
+
+### 2. Configure Plugin
+
+Update `src/config/plugin.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
-    },
-
-    // ... 其他配置
+  list: ["Cacheable"], // Plugin loading order
+  config: {
+    Cacheable: {
+      cacheTimeout: 300,        // 默认缓存过期时间（秒）
+      delayedDoubleDeletion: true, // 默认启用延迟双删策略
+      redisConfig: {
+        host: "127.0.0.1",
+        port: 6379,
+        password: "",
+        db: 0,
+        keyPrefix: "koatty:cache:"
+      }
+    }
+  }
 };
 ```
 
@@ -53,13 +74,15 @@ export default {
 
 ```typescript
 import { CacheAble, CacheEvict, GetCacheStore } from "koatty_cacheable";
+import { Component } from "koatty_container";
 
+@Component()
 export class UserService {
 
     // 自动缓存方法返回值
     @CacheAble("userCache", {
         params: ["id"],    // 使用 id 参数作为缓存键的一部分
-        timeout: 300       // 缓存过期时间（秒），默认 300 秒
+        timeout: 300       // 缓存过期时间（秒），默认使用插件配置的 cacheTimeout
     })
     async getUserById(id: string): Promise<User> {
         // 数据库查询逻辑
@@ -69,7 +92,7 @@ export class UserService {
     // 自动清除相关缓存
     @CacheEvict("userCache", {
         params: ["id"],                    // 使用 id 参数定位要清除的缓存
-        delayedDoubleDeletion: true        // 启用延迟双删策略，默认 true
+        delayedDoubleDeletion: true        // 启用延迟双删策略，默认使用插件配置的 delayedDoubleDeletion
     })
     async updateUser(id: string, userData: Partial<User>): Promise<User> {
         // 更新用户数据
@@ -96,6 +119,9 @@ export class UserService {
 ### 高级用法
 
 ```typescript
+import { Component } from "koatty_container";
+
+@Component()
 export class ProductService {
 
     // 无参数缓存
@@ -107,7 +133,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);
@@ -116,7 +142,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);
@@ -176,12 +202,33 @@ 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. 装饰器只能用于 `SERVICE` 和 `COMPONENT` 类型的类
-2. 被装饰的方法必须是异步方法（返回 Promise）
-3. 缓存的数据会自动进行 JSON 序列化/反序列化
-4. 如果缓存服务不可用，方法会正常执行，不会抛出错误
+1. 缓存的数据会自动进行 JSON 序列化/反序列化
+2. 如果缓存服务不可用，方法会正常执行，不会抛出错误
+3. 插件会在应用启动时自动注入缓存功能到所有使用装饰器的方法
 
 ## 许可证
 

package/dist/index.d.ts

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