BREAKING CHANGE(core): Refactor to v3: introduce modular core/domain architecture, plugin system, observability and strict TypeScript configuration; remove legacy classes

ts/domain/kv/index.ts

@@ -0,0 +1,27 @@
+/**
+ * Key-Value Store Module
+ *
+ * Distributed caching with TTL support
+ */
+
+// Main classes
+export { KVStore, createKVStore } from './kv-store.js';
+
+// Types
+export type {
+  KVOperationResult,
+  KVSetOptions,
+  KVGetOptions,
+  KVDeleteOptions,
+  KVScanOptions,
+  KVScanResult,
+  CacheEvictionPolicy,
+  CacheStats,
+  KVStoreConfig,
+  KVStoreStats,
+  KVDocument,
+  CacheEntry,
+  KVBatchGetResult,
+  KVBatchSetResult,
+  KVBatchDeleteResult,
+} from './types.js';

ts/domain/kv/types.ts

@@ -0,0 +1,345 @@
+/**
+ * Key-Value Store types for distributed caching with TTL support
+ */
+
+/**
+ * KV operation result
+ */
+export interface KVOperationResult<T = unknown> {
+  /** Whether operation succeeded */
+  success: boolean;
+
+  /** Retrieved value (for get operations) */
+  value?: T;
+
+  /** Whether key exists */
+  exists: boolean;
+
+  /** Error if operation failed */
+  error?: {
+    type: string;
+    reason: string;
+  };
+
+  /** Version info for optimistic concurrency */
+  version?: {
+    seqNo: number;
+    primaryTerm: number;
+  };
+
+  /** Expiration timestamp (for TTL keys) */
+  expiresAt?: Date;
+
+  /** Cache hit/miss info */
+  cacheHit?: boolean;
+}
+
+/**
+ * KV set options
+ */
+export interface KVSetOptions {
+  /** Time-to-live in seconds */
+  ttl?: number;
+
+  /** Only set if key doesn't exist */
+  nx?: boolean;
+
+  /** Only set if key exists */
+  xx?: boolean;
+
+  /** Optimistic concurrency control */
+  ifSeqNo?: number;
+  ifPrimaryTerm?: number;
+
+  /** Routing value */
+  routing?: string;
+
+  /** Pipeline to execute */
+  pipeline?: string;
+
+  /** Skip cache and write directly to Elasticsearch */
+  skipCache?: boolean;
+}
+
+/**
+ * KV get options
+ */
+export interface KVGetOptions {
+  /** Return default value if key doesn't exist */
+  default?: unknown;
+
+  /** Skip cache and read directly from Elasticsearch */
+  skipCache?: boolean;
+
+  /** Routing value */
+  routing?: string;
+}
+
+/**
+ * KV delete options
+ */
+export interface KVDeleteOptions {
+  /** Optimistic concurrency control */
+  ifSeqNo?: number;
+  ifPrimaryTerm?: number;
+
+  /** Routing value */
+  routing?: string;
+
+  /** Also remove from cache */
+  invalidateCache?: boolean;
+}
+
+/**
+ * KV scan options
+ */
+export interface KVScanOptions {
+  /** Pattern to match keys (supports wildcards) */
+  pattern?: string;
+
+  /** Maximum keys to return */
+  limit?: number;
+
+  /** Scroll cursor for pagination */
+  cursor?: string;
+
+  /** Include values in scan results */
+  includeValues?: boolean;
+
+  /** Routing value */
+  routing?: string;
+}
+
+/**
+ * KV scan result
+ */
+export interface KVScanResult<T = unknown> {
+  /** Matched keys */
+  keys: string[];
+
+  /** Values (if includeValues was true) */
+  values?: T[];
+
+  /** Next cursor for pagination */
+  nextCursor?: string;
+
+  /** Total matches found */
+  total: number;
+
+  /** Whether there are more results */
+  hasMore: boolean;
+}
+
+/**
+ * Cache eviction policy
+ */
+export type CacheEvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl';
+
+/**
+ * Cache statistics
+ */
+export interface CacheStats {
+  /** Total cache entries */
+  size: number;
+
+  /** Maximum cache size */
+  maxSize: number;
+
+  /** Cache hits */
+  hits: number;
+
+  /** Cache misses */
+  misses: number;
+
+  /** Hit ratio */
+  hitRatio: number;
+
+  /** Total evictions */
+  evictions: number;
+
+  /** Memory usage estimate (bytes) */
+  memoryUsage: number;
+}
+
+/**
+ * KV Store configuration
+ */
+export interface KVStoreConfig {
+  /** Index name for key-value storage */
+  index: string;
+
+  /** Default TTL in seconds */
+  defaultTTL?: number;
+
+  /** Enable in-memory caching */
+  enableCache?: boolean;
+
+  /** Maximum cache entries */
+  cacheMaxSize?: number;
+
+  /** Cache eviction policy */
+  cacheEvictionPolicy?: CacheEvictionPolicy;
+
+  /** Cache TTL in seconds (separate from KV TTL) */
+  cacheTTL?: number;
+
+  /** Enable automatic expiration cleanup */
+  enableExpirationCleanup?: boolean;
+
+  /** Expiration cleanup interval in seconds */
+  cleanupIntervalSeconds?: number;
+
+  /** Batch size for cleanup operations */
+  cleanupBatchSize?: number;
+
+  /** Default routing for all operations */
+  defaultRouting?: string;
+
+  /** Enable compression for large values */
+  enableCompression?: boolean;
+
+  /** Compression threshold in bytes */
+  compressionThreshold?: number;
+
+  /** Refresh policy */
+  refresh?: boolean | 'wait_for';
+
+  /** Enable optimistic concurrency by default */
+  enableOptimisticConcurrency?: boolean;
+}
+
+/**
+ * KV Store statistics
+ */
+export interface KVStoreStats {
+  /** Total keys stored */
+  totalKeys: number;
+
+  /** Total get operations */
+  totalGets: number;
+
+  /** Total set operations */
+  totalSets: number;
+
+  /** Total delete operations */
+  totalDeletes: number;
+
+  /** Total scan operations */
+  totalScans: number;
+
+  /** Total expired keys cleaned */
+  totalExpired: number;
+
+  /** Cache statistics */
+  cacheStats?: CacheStats;
+
+  /** Average operation duration */
+  avgGetDurationMs: number;
+  avgSetDurationMs: number;
+  avgDeleteDurationMs: number;
+
+  /** Storage size estimate (bytes) */
+  storageSize: number;
+}
+
+/**
+ * Internal KV document structure
+ */
+export interface KVDocument<T = unknown> {
+  /** The key */
+  key: string;
+
+  /** The value */
+  value: T;
+
+  /** Creation timestamp */
+  createdAt: Date;
+
+  /** Last update timestamp */
+  updatedAt: Date;
+
+  /** Expiration timestamp (null = no expiration) */
+  expiresAt: Date | null;
+
+  /** Metadata */
+  metadata?: {
+    size?: number;
+    compressed?: boolean;
+    contentType?: string;
+    tags?: string[];
+  };
+}
+
+/**
+ * Cache entry
+ */
+export interface CacheEntry<T = unknown> {
+  /** Cached value */
+  value: T;
+
+  /** Cache entry creation time */
+  cachedAt: Date;
+
+  /** Cache entry expiration time */
+  expiresAt?: Date;
+
+  /** Last access time (for LRU) */
+  lastAccessedAt: Date;
+
+  /** Access count (for LFU) */
+  accessCount: number;
+
+  /** Entry size estimate */
+  size: number;
+
+  /** Version info */
+  version?: {
+    seqNo: number;
+    primaryTerm: number;
+  };
+}
+
+/**
+ * Batch get result
+ */
+export interface KVBatchGetResult<T = unknown> {
+  /** Key-value map of results */
+  results: Map<string, KVOperationResult<T>>;
+
+  /** Number of keys found */
+  found: number;
+
+  /** Number of keys not found */
+  notFound: number;
+
+  /** Cache hit count */
+  cacheHits: number;
+}
+
+/**
+ * Batch set result
+ */
+export interface KVBatchSetResult {
+  /** Number of successful sets */
+  successful: number;
+
+  /** Number of failed sets */
+  failed: number;
+
+  /** Individual results */
+  results: Map<string, KVOperationResult>;
+}
+
+/**
+ * Batch delete result
+ */
+export interface KVBatchDeleteResult {
+  /** Number of successful deletes */
+  successful: number;
+
+  /** Number of failed deletes */
+  failed: number;
+
+  /** Individual results */
+  results: Map<string, KVOperationResult>;
+}