@nest-omni/core 4.1.3-0 → 4.1.3-10

package/cache/dependencies/db.dependency.d.ts

@@ -1,15 +1,60 @@
 import { DataSource } from 'typeorm';
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * Database-based cache dependency
+ *
+ * This dependency monitors database query results. When the query result changes,
+ * the cache becomes invalid.
+ *
+ * Common use case: Monitor MAX(updated_at) or COUNT(*) to detect data changes.
+ *
+ * @example
+ * ```typescript
+ * // Invalidate cache when user data changes
+ * @Cacheable({
+ *   key: (id) => `user:${id}:profile`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT updated_at FROM users WHERE id = ?',
+ *       (id) => [id]
+ *     )
+ *   ]
+ * })
+ * async getUserProfile(id: string) { }
+ *
+ * // Invalidate when any user in tenant changes
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT MAX(updated_at) FROM users WHERE tenant_id = ?',
+ *       (tenantId) => [tenantId]
+ *     )
+ *   ]
+ * })
+ * async getUserList(tenantId: string) { }
+ * ```
+ */
 export declare class DbDependency implements CacheDependency {
     private readonly sql;
     private readonly paramsFactory?;
     private readonly name?;
     private static dataSource;
     constructor(sql: string, paramsFactory?: (...args: any[]) => any[], name?: string);
+    /**
+     * Set the TypeORM DataSource for database queries
+     * This should be called once during application initialization
+     */
     static setDataSource(dataSource: DataSource): void;
+    /**
+     * Get the current DataSource
+     */
     static getDataSource(): DataSource | null;
     getKey(): string;
     getData(): Promise<any>;
     isChanged(oldData: any): Promise<boolean>;
+    /**
+     * Simple hash code generation for strings
+     */
     private hashCode;
 }

package/cache/dependencies/db.dependency.js

@@ -10,6 +10,41 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DbDependency = void 0;
+/**
+ * Database-based cache dependency
+ *
+ * This dependency monitors database query results. When the query result changes,
+ * the cache becomes invalid.
+ *
+ * Common use case: Monitor MAX(updated_at) or COUNT(*) to detect data changes.
+ *
+ * @example
+ * ```typescript
+ * // Invalidate cache when user data changes
+ * @Cacheable({
+ *   key: (id) => `user:${id}:profile`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT updated_at FROM users WHERE id = ?',
+ *       (id) => [id]
+ *     )
+ *   ]
+ * })
+ * async getUserProfile(id: string) { }
+ *
+ * // Invalidate when any user in tenant changes
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [
+ *     new DbDependency(
+ *       'SELECT MAX(updated_at) FROM users WHERE tenant_id = ?',
+ *       (tenantId) => [tenantId]
+ *     )
+ *   ]
+ * })
+ * async getUserList(tenantId: string) { }
+ * ```
+ */
 class DbDependency {
     constructor(sql, paramsFactory, name) {
         this.sql = sql;
@@ -19,9 +54,16 @@ class DbDependency {
             throw new Error('DbDependency requires a valid SQL query');
         }
     }
+    /**
+     * Set the TypeORM DataSource for database queries
+     * This should be called once during application initialization
+     */
     static setDataSource(dataSource) {
         this.dataSource = dataSource;
     }
+    /**
+     * Get the current DataSource
+     */
     static getDataSource() {
         return this.dataSource;
     }
@@ -39,6 +81,7 @@ class DbDependency {
             try {
                 const params = ((_a = this.paramsFactory) === null || _a === void 0 ? void 0 : _a.call(this)) || [];
                 const result = yield DbDependency.dataSource.query(this.sql, params);
+                // Serialize result for comparison
                 return JSON.stringify(result);
             }
             catch (error) {
@@ -53,16 +96,20 @@ class DbDependency {
                 return oldData !== currentData;
             }
             catch (_a) {
+                // If query fails, consider it changed to be safe
                 return true;
             }
         });
     }
+    /**
+     * Simple hash code generation for strings
+     */
     hashCode(str) {
         let hash = 0;
         for (let i = 0; i < str.length; i++) {
             const char = str.charCodeAt(i);
             hash = (hash << 5) - hash + char;
-            hash = hash & hash;
+            hash = hash & hash; // Convert to 32bit integer
         }
         return Math.abs(hash).toString(36);
     }

package/cache/dependencies/file.dependency.d.ts

@@ -1,4 +1,33 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * File-based cache dependency
+ *
+ * This dependency monitors file modification time. When the file is modified,
+ * the cache becomes invalid.
+ *
+ * Useful for configuration files, templates, or other file-based resources.
+ *
+ * @example
+ * ```typescript
+ * // Cache template, invalidate when template file changes
+ * @Cacheable({
+ *   key: (name) => `template:${name}`,
+ *   dependencies: [
+ *     new FileDependency((name) => `./templates/${name}.html`)
+ *   ]
+ * })
+ * async getTemplate(name: string) { }
+ *
+ * // Cache config, invalidate when config file changes
+ * @Cacheable({
+ *   key: 'app:config',
+ *   dependencies: [
+ *     new FileDependency('./config/app.json')
+ *   ]
+ * })
+ * async getConfig() { }
+ * ```
+ */
 export declare class FileDependency implements CacheDependency {
     private readonly filePath;
     constructor(filePath: string | ((...args: any[]) => string));
@@ -13,5 +42,8 @@ export declare class FileDependency implements CacheDependency {
         mtime: number;
         size: number;
     } | null): Promise<boolean>;
+    /**
+     * Resolve the file path (handle dynamic paths)
+     */
     private resolveFilePath;
 }

package/cache/dependencies/file.dependency.js

@@ -11,6 +11,35 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.FileDependency = void 0;
 const node_fs_1 = require("node:fs");
+/**
+ * File-based cache dependency
+ *
+ * This dependency monitors file modification time. When the file is modified,
+ * the cache becomes invalid.
+ *
+ * Useful for configuration files, templates, or other file-based resources.
+ *
+ * @example
+ * ```typescript
+ * // Cache template, invalidate when template file changes
+ * @Cacheable({
+ *   key: (name) => `template:${name}`,
+ *   dependencies: [
+ *     new FileDependency((name) => `./templates/${name}.html`)
+ *   ]
+ * })
+ * async getTemplate(name: string) { }
+ *
+ * // Cache config, invalidate when config file changes
+ * @Cacheable({
+ *   key: 'app:config',
+ *   dependencies: [
+ *     new FileDependency('./config/app.json')
+ *   ]
+ * })
+ * async getConfig() { }
+ * ```
+ */
 class FileDependency {
     constructor(filePath) {
         if (!filePath) {
@@ -42,15 +71,20 @@ class FileDependency {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 const currentData = yield this.getData();
+                // File path changed or mtime changed or size changed
                 return (currentData.path !== oldData.path ||
                     currentData.mtime !== oldData.mtime ||
                     currentData.size !== oldData.size);
             }
             catch (_a) {
+                // If we can't access file, consider it changed
                 return true;
             }
         });
     }
+    /**
+     * Resolve the file path (handle dynamic paths)
+     */
     resolveFilePath() {
         return __awaiter(this, void 0, void 0, function* () {
             if (typeof this.filePath === 'function') {

package/cache/dependencies/tag.dependency.d.ts

@@ -1,13 +1,49 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * Tag-based cache dependency
+ *
+ * This dependency allows you to invalidate multiple cache entries by tags.
+ * When a tag is invalidated, all cache entries depending on that tag become invalid.
+ *
+ * This is the most commonly used dependency type for managing related cache entries.
+ *
+ * @example
+ * ```typescript
+ * // Cache user list with tag dependency
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [new TagDependency(['user-list', `tenant:${tenantId}`])]
+ * })
+ * async getUserList(tenantId: string) { }
+ *
+ * // When creating a new user, invalidate the tag
+ * await cacheService.invalidateTags(['user-list']);
+ * ```
+ */
 export declare class TagDependency implements CacheDependency {
     private readonly tags;
     private static readonly PREFIX;
     private static tagVersions;
     constructor(tags: string[]);
+    /**
+     * Get current version of a tag
+     */
     static getTagVersion(tag: string): number;
+    /**
+     * Invalidate a tag (increment its version)
+     */
     static invalidateTag(tag: string): void;
+    /**
+     * Invalidate multiple tags
+     */
     static invalidateTags(tags: string[]): void;
+    /**
+     * Reset all tag versions (useful for testing)
+     */
     static resetAllTags(): void;
+    /**
+     * Get all tags and their versions
+     */
     static getAllTags(): Map<string, number>;
     getKey(): string;
     getData(): Promise<Record<string, number>>;

package/cache/dependencies/tag.dependency.js

@@ -10,6 +10,27 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TagDependency = void 0;
+/**
+ * Tag-based cache dependency
+ *
+ * This dependency allows you to invalidate multiple cache entries by tags.
+ * When a tag is invalidated, all cache entries depending on that tag become invalid.
+ *
+ * This is the most commonly used dependency type for managing related cache entries.
+ *
+ * @example
+ * ```typescript
+ * // Cache user list with tag dependency
+ * @Cacheable({
+ *   key: (tenantId) => `users:list:${tenantId}`,
+ *   dependencies: [new TagDependency(['user-list', `tenant:${tenantId}`])]
+ * })
+ * async getUserList(tenantId: string) { }
+ *
+ * // When creating a new user, invalidate the tag
+ * await cacheService.invalidateTags(['user-list']);
+ * ```
+ */
 class TagDependency {
     constructor(tags) {
         this.tags = tags;
@@ -17,21 +38,36 @@ class TagDependency {
             throw new Error('TagDependency requires at least one tag');
         }
     }
+    /**
+     * Get current version of a tag
+     */
     static getTagVersion(tag) {
         return this.tagVersions.get(tag) || 0;
     }
+    /**
+     * Invalidate a tag (increment its version)
+     */
     static invalidateTag(tag) {
         const currentVersion = this.tagVersions.get(tag) || 0;
         this.tagVersions.set(tag, currentVersion + 1);
     }
+    /**
+     * Invalidate multiple tags
+     */
     static invalidateTags(tags) {
         for (const tag of tags) {
             this.invalidateTag(tag);
         }
     }
+    /**
+     * Reset all tag versions (useful for testing)
+     */
     static resetAllTags() {
         this.tagVersions.clear();
     }
+    /**
+     * Get all tags and their versions
+     */
     static getAllTags() {
         return new Map(this.tagVersions);
     }

package/cache/dependencies/time.dependency.d.ts

@@ -1,4 +1,38 @@
 import type { CacheDependency } from '../interfaces/cache-dependency.interface';
+/**
+ * Time-based cache dependency
+ *
+ * This dependency invalidates cache after a specific duration.
+ * Unlike TTL which is checked on read, this is checked as a dependency.
+ *
+ * Useful for implementing complex time-based invalidation logic.
+ *
+ * @example
+ * ```typescript
+ * // Cache for 5 minutes
+ * @Cacheable({
+ *   key: 'daily:report',
+ *   dependencies: [
+ *     new TimeDependency(5 * 60 * 1000) // 5 minutes
+ *   ]
+ * })
+ * async getDailyReport() { }
+ *
+ * // Cache until midnight
+ * @Cacheable({
+ *   key: 'today:stats',
+ *   dependencies: [
+ *     new TimeDependency(() => {
+ *       const now = new Date();
+ *       const midnight = new Date(now);
+ *       midnight.setHours(24, 0, 0, 0);
+ *       return midnight.getTime() - now.getTime();
+ *     })
+ *   ]
+ * })
+ * async getTodayStats() { }
+ * ```
+ */
 export declare class TimeDependency implements CacheDependency {
     private readonly duration;
     private createdAt;
@@ -13,7 +47,16 @@ export declare class TimeDependency implements CacheDependency {
         duration: number;
     }): Promise<boolean>;
     reset(): Promise<void>;
+    /**
+     * Get remaining time in milliseconds
+     */
     getRemainingTime(): number;
+    /**
+     * Check if dependency has expired
+     */
     isExpired(): boolean;
+    /**
+     * Resolve duration value (handle dynamic duration)
+     */
     private resolveDuration;
 }

package/cache/dependencies/time.dependency.js

@@ -10,6 +10,40 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.TimeDependency = void 0;
+/**
+ * Time-based cache dependency
+ *
+ * This dependency invalidates cache after a specific duration.
+ * Unlike TTL which is checked on read, this is checked as a dependency.
+ *
+ * Useful for implementing complex time-based invalidation logic.
+ *
+ * @example
+ * ```typescript
+ * // Cache for 5 minutes
+ * @Cacheable({
+ *   key: 'daily:report',
+ *   dependencies: [
+ *     new TimeDependency(5 * 60 * 1000) // 5 minutes
+ *   ]
+ * })
+ * async getDailyReport() { }
+ *
+ * // Cache until midnight
+ * @Cacheable({
+ *   key: 'today:stats',
+ *   dependencies: [
+ *     new TimeDependency(() => {
+ *       const now = new Date();
+ *       const midnight = new Date(now);
+ *       midnight.setHours(24, 0, 0, 0);
+ *       return midnight.getTime() - now.getTime();
+ *     })
+ *   ]
+ * })
+ * async getTodayStats() { }
+ * ```
+ */
 class TimeDependency {
     constructor(duration) {
         if (typeof duration !== 'number' && typeof duration !== 'function') {
@@ -48,15 +82,24 @@ class TimeDependency {
             this.createdAt = Date.now();
         });
     }
+    /**
+     * Get remaining time in milliseconds
+     */
     getRemainingTime() {
         const duration = this.resolveDuration();
         const elapsed = Date.now() - this.createdAt;
         const remaining = duration - elapsed;
         return Math.max(0, remaining);
     }
+    /**
+     * Check if dependency has expired
+     */
     isExpired() {
         return this.getRemainingTime() === 0;
     }
+    /**
+     * Resolve duration value (handle dynamic duration)
+     */
     resolveDuration() {
         if (typeof this.duration === 'function') {
             const value = this.duration();

package/cache/examples/basic-usage.d.ts

@@ -1,3 +1,6 @@
+/**
+ * 基础缓存使用示例
+ */
 import { CacheService } from '../index';
 interface User {
     id: string;
@@ -25,6 +28,9 @@ declare class UserRepository {
 declare class PostRepository {
     findByAuthor(authorId: string): Promise<Post[]>;
 }
+/**
+ * 用户服务示例
+ */
 export declare class UserService {
     private cacheService;
     private userRepository;
@@ -39,6 +45,9 @@ export declare class UserService {
     cacheLargeData(id: string): Promise<void>;
     getLargeData(id: string): Promise<any>;
 }
+/**
+ * 文章服务示例 - 展示依赖使用
+ */
 export declare class PostService {
     private cacheService;
     private postRepository;
@@ -47,6 +56,9 @@ export declare class PostService {
     getFeaturedPosts(): Promise<Post[]>;
     private getConfigVersion;
 }
+/**
+ * 缓存统计和监控示例
+ */
 export declare class CacheMonitoringService {
     private cacheService;
     constructor(cacheService: CacheService);
@@ -54,5 +66,8 @@ export declare class CacheMonitoringService {
     resetStats(): void;
     startMonitoring(intervalMs?: number): void;
 }
+/**
+ * 使用示例
+ */
 declare function demonstrateCacheUsage(): Promise<void>;
 export { demonstrateCacheUsage };