@ooples/token-optimizer-mcp
Version:
Intelligent context window optimization for Claude Code - store content externally via caching and compression, freeing up your context window for what matters
366 lines • 12.5 kB
TypeScript
/**
* Cache Invalidation - 88% token reduction through intelligent cache invalidation
*
* Features:
* - Multiple invalidation strategies (immediate, lazy, write-through, TTL, event-driven, dependency-cascade)
* - Dependency graph tracking with parent-child relationships
* - Pattern-based invalidation with wildcard support
* - Partial invalidation (field-level updates)
* - Scheduled invalidation with cron support
* - Invalidation audit trail
* - Smart re-validation (only validate if needed)
* - Batch invalidation with atomic guarantees
*/
import { CacheEngine } from '../../core/cache-engine.js';
import { TokenCounter } from '../../core/token-counter.js';
import { MetricsCollector } from '../../core/metrics.js';
import { EventEmitter } from 'events';
import { CacheInvalidationEvent } from '../../core/types.js';
export type InvalidationStrategy = 'immediate' | 'lazy' | 'write-through' | 'ttl-based' | 'event-driven' | 'dependency-cascade';
export type InvalidationMode = 'eager' | 'lazy' | 'scheduled';
export interface CacheInvalidationOptions {
operation: 'invalidate' | 'invalidate-pattern' | 'invalidate-tag' | 'invalidate-dependency' | 'schedule-invalidation' | 'cancel-scheduled' | 'audit-log' | 'set-dependency' | 'remove-dependency' | 'validate' | 'configure' | 'stats' | 'clear-audit';
key?: string;
keys?: string[];
pattern?: string;
tag?: string;
tags?: string[];
parentKey?: string;
childKey?: string;
childKeys?: string[];
cascadeDepth?: number;
scheduleId?: string;
cronExpression?: string;
executeAt?: number;
repeatInterval?: number;
strategy?: InvalidationStrategy;
mode?: InvalidationMode;
enableAudit?: boolean;
maxAuditEntries?: number;
revalidateOnInvalidate?: boolean;
skipExpired?: boolean;
broadcastToNodes?: boolean;
nodeId?: string;
useCache?: boolean;
cacheTTL?: number;
}
export interface DependencyNode {
key: string;
parents: Set<string>;
children: Set<string>;
tags: Set<string>;
createdAt: number;
lastInvalidated: number | null;
}
export interface InvalidationRecord {
id: string;
timestamp: number;
strategy: InvalidationStrategy;
affectedKeys: string[];
reason: string;
metadata: Record<string, unknown>;
executionTime: number;
}
export interface ScheduledInvalidation {
id: string;
keys: string[];
pattern?: string;
tags?: string[];
executeAt: number;
cronExpression?: string;
repeatInterval?: number;
createdAt: number;
lastExecuted: number | null;
executionCount: number;
}
export interface InvalidationStats {
totalInvalidations: number;
invalidationsByStrategy: Record<InvalidationStrategy, number>;
averageInvalidationTime: number;
averageKeysInvalidated: number;
dependencyGraphSize: number;
scheduledInvalidationsCount: number;
auditLogSize: number;
tokensSaved: number;
}
export interface CacheInvalidationResult {
success: boolean;
operation: string;
data: {
invalidatedKeys?: string[];
invalidationRecord?: InvalidationRecord;
auditLog?: InvalidationRecord[];
dependency?: DependencyNode;
scheduledInvalidation?: ScheduledInvalidation;
stats?: InvalidationStats;
validationResults?: Array<{
key: string;
valid: boolean;
reason: string;
}>;
};
metadata: {
tokensUsed: number;
tokensSaved: number;
cacheHit: boolean;
executionTime: number;
};
}
/**
* CacheInvalidationTool - Comprehensive cache invalidation management
*/
export declare class CacheInvalidationTool extends EventEmitter {
private cache;
private tokenCounter;
private metrics;
private dependencyGraph;
private tagIndex;
private auditLog;
private maxAuditEntries;
private enableAudit;
private scheduledInvalidations;
private schedulerTimer;
private strategy;
private mode;
private stats;
private lazyInvalidationQueue;
private lazyProcessTimer;
private nodeId;
private connectedNodes;
constructor(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector, nodeId?: string);
/**
* Main entry point for all cache invalidation operations
*/
run(options: CacheInvalidationOptions): Promise<CacheInvalidationResult>;
/**
* Invalidate specific cache key(s)
*/
private invalidate;
/**
* Invalidate keys matching a pattern
*/
private invalidatePattern;
/**
* Invalidate keys by tag
*/
private invalidateTag;
/**
* Invalidate with dependency cascade
*/
private invalidateDependency;
/**
* Schedule future invalidation
*/
private scheduleInvalidation;
/**
* Cancel scheduled invalidation
*/
private cancelScheduled;
/**
* Get audit log
*/
private getAuditLog;
/**
* Set dependency relationship
*/
private setDependency;
/**
* Remove dependency relationship
*/
private removeDependency;
/**
* Validate cache entries
*/
private validate;
/**
* Configure invalidation settings
*/
private configure;
/**
* Get invalidation statistics
*/
private getStats;
/**
* Clear audit log
*/
private clearAudit;
/**
* Create audit record
*/
private createAuditRecord;
/**
* Pattern to regex conversion
*/
private patternToRegex;
/**
* Start scheduler for processing scheduled invalidations
*/
private startScheduler;
/**
* Process scheduled invalidations
*/
private processScheduledInvalidations;
/**
* Schedule lazy processing
*/
private scheduleLazyProcessing;
/**
* Process lazy invalidation queue
*/
private processLazyInvalidations;
/**
* Broadcast invalidation to distributed nodes
*/
private broadcastInvalidation;
/**
* Generate unique node ID
*/
private generateNodeId;
/**
* Generate unique record ID
*/
private generateRecordId;
/**
* Generate unique schedule ID
*/
private generateScheduleId;
/**
* Determine if operation is cacheable
*/
private isCacheableOperation;
/**
* Get cache key parameters for operation
*/
private getCacheKeyParams;
/**
* Handle external invalidation event
*/
handleExternalEvent(event: CacheInvalidationEvent): void;
/**
* Cleanup and dispose
*/
dispose(): void;
}
export declare function getCacheInvalidationTool(cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector, nodeId?: string): CacheInvalidationTool;
export declare const CACHE_INVALIDATION_TOOL_DEFINITION: {
readonly name: "cache_invalidation";
readonly description: "Comprehensive cache invalidation with 88%+ token reduction, dependency tracking, pattern matching, scheduled invalidation, and distributed coordination";
readonly inputSchema: {
readonly type: "object";
readonly properties: {
readonly operation: {
readonly type: "string";
readonly enum: readonly ["invalidate", "invalidate-pattern", "invalidate-tag", "invalidate-dependency", "schedule-invalidation", "cancel-scheduled", "audit-log", "set-dependency", "remove-dependency", "validate", "configure", "stats", "clear-audit"];
readonly description: "The cache invalidation operation to perform";
};
readonly key: {
readonly type: "string";
readonly description: "Cache key to invalidate";
};
readonly keys: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Array of cache keys to invalidate";
};
readonly pattern: {
readonly type: "string";
readonly description: "Pattern for matching keys (wildcards: * for any chars, ? for single char)";
};
readonly tag: {
readonly type: "string";
readonly description: "Tag to invalidate all associated keys";
};
readonly tags: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Array of tags to invalidate";
};
readonly parentKey: {
readonly type: "string";
readonly description: "Parent key for dependency relationship";
};
readonly childKey: {
readonly type: "string";
readonly description: "Child key for dependency relationship";
};
readonly childKeys: {
readonly type: "array";
readonly items: {
readonly type: "string";
};
readonly description: "Array of child keys for dependency relationship";
};
readonly cascadeDepth: {
readonly type: "number";
readonly description: "Maximum depth for dependency cascade (default: 10)";
};
readonly scheduleId: {
readonly type: "string";
readonly description: "ID of scheduled invalidation";
};
readonly cronExpression: {
readonly type: "string";
readonly description: "Cron expression for scheduled invalidation";
};
readonly executeAt: {
readonly type: "number";
readonly description: "Timestamp when to execute invalidation";
};
readonly repeatInterval: {
readonly type: "number";
readonly description: "Interval in ms for repeating scheduled invalidation";
};
readonly strategy: {
readonly type: "string";
readonly enum: readonly ["immediate", "lazy", "write-through", "ttl-based", "event-driven", "dependency-cascade"];
readonly description: "Invalidation strategy";
};
readonly mode: {
readonly type: "string";
readonly enum: readonly ["eager", "lazy", "scheduled"];
readonly description: "Invalidation mode";
};
readonly enableAudit: {
readonly type: "boolean";
readonly description: "Enable audit logging (default: true)";
};
readonly maxAuditEntries: {
readonly type: "number";
readonly description: "Maximum audit log entries to keep (default: 10000)";
};
readonly revalidateOnInvalidate: {
readonly type: "boolean";
readonly description: "Trigger revalidation after invalidation";
};
readonly skipExpired: {
readonly type: "boolean";
readonly description: "Skip expired entries during validation (default: true)";
};
readonly broadcastToNodes: {
readonly type: "boolean";
readonly description: "Broadcast invalidation to distributed nodes";
};
readonly nodeId: {
readonly type: "string";
readonly description: "Node ID for distributed coordination";
};
readonly useCache: {
readonly type: "boolean";
readonly description: "Enable result caching (default: true)";
readonly default: true;
};
readonly cacheTTL: {
readonly type: "number";
readonly description: "Cache TTL in seconds (default: 300)";
readonly default: 300;
};
};
readonly required: readonly ["operation"];
};
};
export declare function runCacheInvalidation(options: CacheInvalidationOptions, cache: CacheEngine, tokenCounter: TokenCounter, metrics: MetricsCollector, nodeId?: string): Promise<CacheInvalidationResult>;
//# sourceMappingURL=cache-invalidation.d.ts.map