@weavelogic/knowledge-graph-agent 0.2.0 → 0.4.0

package/dist/caching/index.js

@@ -0,0 +1,206 @@
+class AdvancedCache {
+  cache = /* @__PURE__ */ new Map();
+  config;
+  stats = {
+    hits: 0,
+    misses: 0,
+    hitRate: 0,
+    entryCount: 0,
+    currentSize: 0,
+    evictions: 0
+  };
+  constructor(config = {}) {
+    this.config = {
+      maxSize: config.maxSize || 100 * 1024 * 1024,
+      maxEntries: config.maxEntries || 1e4,
+      defaultTtl: config.defaultTtl || 36e5,
+      evictionPolicy: config.evictionPolicy || "lru",
+      enableStats: config.enableStats ?? true
+    };
+  }
+  get(key) {
+    const entry = this.cache.get(key);
+    if (!entry) {
+      if (this.config.enableStats) {
+        this.stats.misses++;
+        this.updateHitRate();
+      }
+      return void 0;
+    }
+    if (entry.ttl && Date.now() - entry.createdAt > entry.ttl) {
+      this.delete(key);
+      if (this.config.enableStats) {
+        this.stats.misses++;
+        this.updateHitRate();
+      }
+      return void 0;
+    }
+    entry.accessedAt = Date.now();
+    entry.accessCount++;
+    if (this.config.enableStats) {
+      this.stats.hits++;
+      this.updateHitRate();
+    }
+    return entry.value;
+  }
+  set(key, value, ttl) {
+    const size = this.estimateSize(value);
+    while (this.shouldEvict(size)) {
+      this.evictOne();
+    }
+    const entry = {
+      key,
+      value,
+      createdAt: Date.now(),
+      accessedAt: Date.now(),
+      accessCount: 1,
+      ttl: ttl || this.config.defaultTtl,
+      size
+    };
+    const existing = this.cache.get(key);
+    if (existing) {
+      this.stats.currentSize -= existing.size;
+    }
+    this.stats.currentSize += size;
+    this.cache.set(key, entry);
+    this.stats.entryCount = this.cache.size;
+  }
+  delete(key) {
+    const entry = this.cache.get(key);
+    if (entry) {
+      this.stats.currentSize -= entry.size;
+      this.cache.delete(key);
+      this.stats.entryCount = this.cache.size;
+      return true;
+    }
+    return false;
+  }
+  has(key) {
+    const entry = this.cache.get(key);
+    if (!entry) return false;
+    if (entry.ttl && Date.now() - entry.createdAt > entry.ttl) {
+      this.delete(key);
+      return false;
+    }
+    return true;
+  }
+  clear() {
+    this.cache.clear();
+    this.stats.currentSize = 0;
+    this.stats.entryCount = 0;
+  }
+  getStats() {
+    return { ...this.stats };
+  }
+  keys() {
+    return Array.from(this.cache.keys());
+  }
+  size() {
+    return this.cache.size;
+  }
+  prune() {
+    let pruned = 0;
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (entry.ttl && now - entry.createdAt > entry.ttl) {
+        this.delete(key);
+        pruned++;
+      }
+    }
+    return pruned;
+  }
+  shouldEvict(newSize) {
+    if (this.cache.size >= this.config.maxEntries) return true;
+    if (this.stats.currentSize + newSize > this.config.maxSize) return true;
+    return false;
+  }
+  evictOne() {
+    if (this.cache.size === 0) return;
+    let keyToEvict = null;
+    switch (this.config.evictionPolicy) {
+      case "lru":
+        keyToEvict = this.findLRU();
+        break;
+      case "lfu":
+        keyToEvict = this.findLFU();
+        break;
+      case "fifo":
+        keyToEvict = this.findFIFO();
+        break;
+      case "ttl":
+        keyToEvict = this.findOldestTTL();
+        break;
+    }
+    if (keyToEvict) {
+      this.delete(keyToEvict);
+      this.stats.evictions++;
+    }
+  }
+  findLRU() {
+    let oldest = null;
+    let oldestKey = null;
+    for (const [key, entry] of this.cache) {
+      if (!oldest || entry.accessedAt < oldest.accessedAt) {
+        oldest = entry;
+        oldestKey = key;
+      }
+    }
+    return oldestKey;
+  }
+  findLFU() {
+    let least = null;
+    let leastKey = null;
+    for (const [key, entry] of this.cache) {
+      if (!least || entry.accessCount < least.accessCount) {
+        least = entry;
+        leastKey = key;
+      }
+    }
+    return leastKey;
+  }
+  findFIFO() {
+    let oldest = null;
+    let oldestKey = null;
+    for (const [key, entry] of this.cache) {
+      if (!oldest || entry.createdAt < oldest.createdAt) {
+        oldest = entry;
+        oldestKey = key;
+      }
+    }
+    return oldestKey;
+  }
+  findOldestTTL() {
+    let closestKey = null;
+    let closestExpiry = Infinity;
+    const now = Date.now();
+    for (const [key, entry] of this.cache) {
+      if (entry.ttl) {
+        const expiry = entry.createdAt + entry.ttl - now;
+        if (expiry < closestExpiry) {
+          closestKey = key;
+          closestExpiry = expiry;
+        }
+      }
+    }
+    return closestKey || this.findLRU();
+  }
+  estimateSize(value) {
+    try {
+      return JSON.stringify(value).length * 2;
+    } catch {
+      return 1024;
+    }
+  }
+  updateHitRate() {
+    const total = this.stats.hits + this.stats.misses;
+    this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;
+  }
+}
+function createAdvancedCache(config) {
+  return new AdvancedCache(config);
+}
+export {
+  AdvancedCache,
+  createAdvancedCache
+};
+//# sourceMappingURL=index.js.map

package/dist/caching/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../src/caching/index.ts"],"sourcesContent":["/**\n * Advanced Caching Module\n *\n * Provides configurable caching with multiple eviction policies.\n */\n\n// ============================================================================\n// Types\n// ============================================================================\n\nexport type EvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl';\n\nexport interface CacheEntry<T> {\n  key: string;\n  value: T;\n  createdAt: number;\n  accessedAt: number;\n  accessCount: number;\n  ttl?: number;\n  size: number;\n}\n\nexport interface CacheConfig {\n  maxSize?: number;\n  maxEntries?: number;\n  defaultTtl?: number;\n  evictionPolicy?: EvictionPolicy;\n  enableStats?: boolean;\n}\n\nexport interface CacheStats {\n  hits: number;\n  misses: number;\n  hitRate: number;\n  entryCount: number;\n  currentSize: number;\n  evictions: number;\n}\n\n// ============================================================================\n// Advanced Cache Implementation\n// ============================================================================\n\nexport class AdvancedCache<T = unknown> {\n  private cache: Map<string, CacheEntry<T>> = new Map();\n  private config: Required<CacheConfig>;\n  private stats: CacheStats = {\n    hits: 0,\n    misses: 0,\n    hitRate: 0,\n    entryCount: 0,\n    currentSize: 0,\n    evictions: 0,\n  };\n\n  constructor(config: CacheConfig = {}) {\n    this.config = {\n      maxSize: config.maxSize || 100 * 1024 * 1024,\n      maxEntries: config.maxEntries || 10000,\n      defaultTtl: config.defaultTtl || 3600000,\n      evictionPolicy: config.evictionPolicy || 'lru',\n      enableStats: config.enableStats ?? true,\n    };\n  }\n\n  get(key: string): T | undefined {\n    const entry = this.cache.get(key);\n    if (!entry) {\n      if (this.config.enableStats) {\n        this.stats.misses++;\n        this.updateHitRate();\n      }\n      return undefined;\n    }\n\n    if (entry.ttl && Date.now() - entry.createdAt > entry.ttl) {\n      this.delete(key);\n      if (this.config.enableStats) {\n        this.stats.misses++;\n        this.updateHitRate();\n      }\n      return undefined;\n    }\n\n    entry.accessedAt = Date.now();\n    entry.accessCount++;\n\n    if (this.config.enableStats) {\n      this.stats.hits++;\n      this.updateHitRate();\n    }\n\n    return entry.value;\n  }\n\n  set(key: string, value: T, ttl?: number): void {\n    const size = this.estimateSize(value);\n\n    while (this.shouldEvict(size)) {\n      this.evictOne();\n    }\n\n    const entry: CacheEntry<T> = {\n      key,\n      value,\n      createdAt: Date.now(),\n      accessedAt: Date.now(),\n      accessCount: 1,\n      ttl: ttl || this.config.defaultTtl,\n      size,\n    };\n\n    const existing = this.cache.get(key);\n    if (existing) {\n      this.stats.currentSize -= existing.size;\n    }\n    this.stats.currentSize += size;\n\n    this.cache.set(key, entry);\n    this.stats.entryCount = this.cache.size;\n  }\n\n  delete(key: string): boolean {\n    const entry = this.cache.get(key);\n    if (entry) {\n      this.stats.currentSize -= entry.size;\n      this.cache.delete(key);\n      this.stats.entryCount = this.cache.size;\n      return true;\n    }\n    return false;\n  }\n\n  has(key: string): boolean {\n    const entry = this.cache.get(key);\n    if (!entry) return false;\n    if (entry.ttl && Date.now() - entry.createdAt > entry.ttl) {\n      this.delete(key);\n      return false;\n    }\n    return true;\n  }\n\n  clear(): void {\n    this.cache.clear();\n    this.stats.currentSize = 0;\n    this.stats.entryCount = 0;\n  }\n\n  getStats(): CacheStats {\n    return { ...this.stats };\n  }\n\n  keys(): string[] {\n    return Array.from(this.cache.keys());\n  }\n\n  size(): number {\n    return this.cache.size;\n  }\n\n  prune(): number {\n    let pruned = 0;\n    const now = Date.now();\n\n    for (const [key, entry] of this.cache) {\n      if (entry.ttl && now - entry.createdAt > entry.ttl) {\n        this.delete(key);\n        pruned++;\n      }\n    }\n\n    return pruned;\n  }\n\n  private shouldEvict(newSize: number): boolean {\n    if (this.cache.size >= this.config.maxEntries) return true;\n    if (this.stats.currentSize + newSize > this.config.maxSize) return true;\n    return false;\n  }\n\n  private evictOne(): void {\n    if (this.cache.size === 0) return;\n\n    let keyToEvict: string | null = null;\n\n    switch (this.config.evictionPolicy) {\n      case 'lru':\n        keyToEvict = this.findLRU();\n        break;\n      case 'lfu':\n        keyToEvict = this.findLFU();\n        break;\n      case 'fifo':\n        keyToEvict = this.findFIFO();\n        break;\n      case 'ttl':\n        keyToEvict = this.findOldestTTL();\n        break;\n    }\n\n    if (keyToEvict) {\n      this.delete(keyToEvict);\n      this.stats.evictions++;\n    }\n  }\n\n  private findLRU(): string | null {\n    let oldest: CacheEntry<T> | null = null;\n    let oldestKey: string | null = null;\n\n    for (const [key, entry] of this.cache) {\n      if (!oldest || entry.accessedAt < oldest.accessedAt) {\n        oldest = entry;\n        oldestKey = key;\n      }\n    }\n    return oldestKey;\n  }\n\n  private findLFU(): string | null {\n    let least: CacheEntry<T> | null = null;\n    let leastKey: string | null = null;\n\n    for (const [key, entry] of this.cache) {\n      if (!least || entry.accessCount < least.accessCount) {\n        least = entry;\n        leastKey = key;\n      }\n    }\n    return leastKey;\n  }\n\n  private findFIFO(): string | null {\n    let oldest: CacheEntry<T> | null = null;\n    let oldestKey: string | null = null;\n\n    for (const [key, entry] of this.cache) {\n      if (!oldest || entry.createdAt < oldest.createdAt) {\n        oldest = entry;\n        oldestKey = key;\n      }\n    }\n    return oldestKey;\n  }\n\n  private findOldestTTL(): string | null {\n    let closest: CacheEntry<T> | null = null;\n    let closestKey: string | null = null;\n    let closestExpiry = Infinity;\n    const now = Date.now();\n\n    for (const [key, entry] of this.cache) {\n      if (entry.ttl) {\n        const expiry = entry.createdAt + entry.ttl - now;\n        if (expiry < closestExpiry) {\n          closest = entry;\n          closestKey = key;\n          closestExpiry = expiry;\n        }\n      }\n    }\n    return closestKey || this.findLRU();\n  }\n\n  private estimateSize(value: T): number {\n    try {\n      return JSON.stringify(value).length * 2;\n    } catch {\n      return 1024;\n    }\n  }\n\n  private updateHitRate(): void {\n    const total = this.stats.hits + this.stats.misses;\n    this.stats.hitRate = total > 0 ? this.stats.hits / total : 0;\n  }\n}\n\nexport function createAdvancedCache<T = unknown>(config?: CacheConfig): AdvancedCache<T> {\n  return new AdvancedCache<T>(config);\n}\n"],"names":[],"mappings":"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"}

package/dist/caching/lru-cache.d.ts

@@ -0,0 +1,254 @@
+/**
+ * LRU Cache Implementation
+ *
+ * Advanced cache implementation supporting multiple eviction policies,
+ * TTL management, tag-based operations, and comprehensive statistics.
+ *
+ * @module caching/lru-cache
+ */
+import { EventEmitter } from 'events';
+import type { CacheConfig, CacheStats, EvictionPolicy, CacheSetOptions } from './types.js';
+/**
+ * Cache event types emitted by AdvancedCache
+ */
+export interface CacheEvents<T> {
+    set: (key: string, value: T) => void;
+    get: (key: string, value: T | undefined) => void;
+    delete: (key: string) => void;
+    evict: (key: string) => void;
+    clear: () => void;
+    expire: (key: string) => void;
+}
+/**
+ * Advanced Cache with multiple eviction policies
+ *
+ * Features:
+ * - LRU, LFU, FIFO, and TTL-based eviction policies
+ * - Tag-based grouping and batch operations
+ * - Automatic TTL expiration with periodic cleanup
+ * - Comprehensive statistics and monitoring
+ * - Event emission for cache operations
+ *
+ * @example
+ * ```typescript
+ * const cache = new AdvancedCache<User>({
+ *   maxSize: 50 * 1024 * 1024, // 50MB
+ *   maxEntries: 1000,
+ *   defaultTTL: 300000, // 5 minutes
+ *   evictionPolicy: 'lru',
+ *   onEvict: (key, value) => console.log(`Evicted: ${key}`)
+ * });
+ *
+ * cache.set('user:123', userData, { tags: ['user', 'active'] });
+ * const user = cache.get<User>('user:123');
+ *
+ * // Delete all entries with 'user' tag
+ * cache.deleteByTag('user');
+ * ```
+ */
+export declare class AdvancedCache<T = any> extends EventEmitter {
+    private cache;
+    private config;
+    private stats;
+    private cleanupTimer?;
+    /**
+     * Create a new AdvancedCache instance
+     *
+     * @param config - Partial cache configuration (defaults will be applied)
+     */
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Get a value from the cache
+     *
+     * @param key - The cache key to retrieve
+     * @returns The cached value or undefined if not found/expired
+     */
+    get<V extends T>(key: string): V | undefined;
+    /**
+     * Set a value in the cache
+     *
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param options - Optional settings for TTL and tags
+     */
+    set(key: string, value: T, options?: CacheSetOptions): void;
+    /**
+     * Check if a key exists in the cache and is not expired
+     *
+     * @param key - The cache key to check
+     * @returns True if key exists and is not expired
+     */
+    has(key: string): boolean;
+    /**
+     * Delete an entry from the cache
+     *
+     * @param key - The cache key to delete
+     * @returns True if the entry was deleted
+     */
+    delete(key: string): boolean;
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): void;
+    /**
+     * Get all entries with a specific tag
+     *
+     * @param tag - The tag to filter by
+     * @returns Array of values with the specified tag
+     */
+    getByTag(tag: string): T[];
+    /**
+     * Get all keys with a specific tag
+     *
+     * @param tag - The tag to filter by
+     * @returns Array of keys with the specified tag
+     */
+    getKeysByTag(tag: string): string[];
+    /**
+     * Delete all entries with a specific tag
+     *
+     * @param tag - The tag to filter by
+     * @returns Number of entries deleted
+     */
+    deleteByTag(tag: string): number;
+    /**
+     * Get all unique tags in the cache
+     *
+     * @returns Set of all tags
+     */
+    getTags(): Set<string>;
+    /**
+     * Get cache statistics
+     *
+     * @returns Current cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset statistics counters
+     */
+    resetStats(): void;
+    /**
+     * Get the current eviction policy
+     */
+    getEvictionPolicy(): EvictionPolicy;
+    /**
+     * Change the eviction policy
+     *
+     * @param policy - The new eviction policy
+     */
+    setEvictionPolicy(policy: EvictionPolicy): void;
+    /**
+     * Get all keys in the cache
+     *
+     * @returns Array of all cache keys
+     */
+    keys(): string[];
+    /**
+     * Get all values in the cache
+     *
+     * @returns Array of all cached values
+     */
+    values(): T[];
+    /**
+     * Get all entries in the cache
+     *
+     * @returns Array of [key, value] pairs
+     */
+    entries(): [string, T][];
+    /**
+     * Get the number of entries in the cache
+     */
+    get size(): number;
+    /**
+     * Update the TTL for an existing entry
+     *
+     * @param key - The cache key
+     * @param ttl - New TTL in milliseconds
+     * @returns True if the entry was updated
+     */
+    touch(key: string, ttl?: number): boolean;
+    /**
+     * Get or set a value using a factory function
+     *
+     * @param key - The cache key
+     * @param factory - Function to create value if not cached
+     * @param options - Optional settings for TTL and tags
+     * @returns The cached or newly created value
+     */
+    getOrSet<V extends T>(key: string, factory: () => V | Promise<V>, options?: CacheSetOptions): Promise<V>;
+    /**
+     * Get or set a value synchronously using a factory function
+     *
+     * @param key - The cache key
+     * @param factory - Function to create value if not cached
+     * @param options - Optional settings for TTL and tags
+     * @returns The cached or newly created value
+     */
+    getOrSetSync<V extends T>(key: string, factory: () => V, options?: CacheSetOptions): V;
+    /**
+     * Check if an entry is expired
+     */
+    private isExpired;
+    /**
+     * Check if eviction is needed for a new entry of given size
+     */
+    private needsEviction;
+    /**
+     * Evict one entry based on the eviction policy
+     *
+     * @returns True if an entry was evicted
+     */
+    private evictOne;
+    /**
+     * Select a candidate for eviction based on policy
+     */
+    private selectEvictionCandidate;
+    /**
+     * Compare two entries for eviction (returns true if entry should be evicted over candidate)
+     */
+    private compareForEviction;
+    /**
+     * Estimate the size of a value in bytes
+     */
+    private estimateSize;
+    /**
+     * Record access time for statistics
+     */
+    private recordAccessTime;
+    /**
+     * Start periodic cleanup of expired entries
+     */
+    private startCleanup;
+    /**
+     * Destroy the cache and release resources
+     */
+    destroy(): void;
+}
+/**
+ * Create a new AdvancedCache instance
+ *
+ * @param config - Partial cache configuration
+ * @returns A new AdvancedCache instance
+ *
+ * @example
+ * ```typescript
+ * const cache = createAdvancedCache<string>({
+ *   maxEntries: 1000,
+ *   evictionPolicy: 'lfu'
+ * });
+ * ```
+ */
+export declare function createAdvancedCache<T = any>(config?: Partial<CacheConfig>): AdvancedCache<T>;
+/**
+ * Create a cache with preloaded entries
+ *
+ * @param entries - Initial entries to populate the cache
+ * @param config - Partial cache configuration
+ * @returns A new AdvancedCache instance with preloaded entries
+ */
+export declare function createPreloadedCache<T = any>(entries: Array<{
+    key: string;
+    value: T;
+    options?: CacheSetOptions;
+}>, config?: Partial<CacheConfig>): AdvancedCache<T>;
+//# sourceMappingURL=lru-cache.d.ts.map

package/dist/caching/lru-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lru-cache.d.ts","sourceRoot":"","sources":["../../src/caching/lru-cache.ts"],"names":[],"mappings":"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"}

package/dist/caching/types.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Advanced Caching Types
+ *
+ * Type definitions for the advanced caching system supporting multiple
+ * eviction policies, TTL management, and comprehensive cache statistics.
+ *
+ * @module caching/types
+ */
+/**
+ * Eviction policy for cache entries when capacity is reached
+ *
+ * - lru: Least Recently Used - evicts entries that haven't been accessed recently
+ * - lfu: Least Frequently Used - evicts entries with lowest access count
+ * - fifo: First In First Out - evicts oldest entries first
+ * - ttl: Time To Live - evicts entries closest to expiration
+ */
+export type EvictionPolicy = 'lru' | 'lfu' | 'fifo' | 'ttl';
+/**
+ * Cache entry storing value with metadata for eviction decisions
+ */
+export interface CacheEntry<T> {
+    /** Unique key for the cache entry */
+    key: string;
+    /** The cached value */
+    value: T;
+    /** Estimated size of the entry in bytes */
+    size: number;
+    /** Unix timestamp when entry was created */
+    createdAt: number;
+    /** Unix timestamp when entry was last accessed */
+    accessedAt: number;
+    /** Number of times entry has been accessed */
+    accessCount: number;
+    /** Time-to-live in milliseconds (optional) */
+    ttl?: number;
+    /** Optional tags for grouping and batch operations */
+    tags?: string[];
+}
+/**
+ * Configuration options for the cache
+ */
+export interface CacheConfig {
+    /** Maximum total size of cache in bytes */
+    maxSize: number;
+    /** Maximum number of entries in cache */
+    maxEntries: number;
+    /** Default TTL for entries in milliseconds */
+    defaultTTL: number;
+    /** Policy used for evicting entries when cache is full */
+    evictionPolicy: EvictionPolicy;
+    /** Optional callback when an entry is evicted */
+    onEvict?: (key: string, value: any) => void;
+}
+/**
+ * Cache statistics for monitoring and diagnostics
+ */
+export interface CacheStats {
+    /** Current number of entries in cache */
+    entries: number;
+    /** Current total size of all entries in bytes */
+    size: number;
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Hit rate as a ratio (0-1) */
+    hitRate: number;
+    /** Total number of evictions */
+    evictions: number;
+    /** Average access time in milliseconds */
+    avgAccessTime: number;
+}
+/**
+ * Options for cache set operations
+ */
+export interface CacheSetOptions {
+    /** TTL override for this entry in milliseconds */
+    ttl?: number;
+    /** Tags for grouping entries */
+    tags?: string[];
+}
+/**
+ * Result of a cache operation with timing information
+ */
+export interface CacheOperationResult<T> {
+    /** Whether the operation succeeded */
+    success: boolean;
+    /** The value if operation was successful */
+    value?: T;
+    /** Time taken for the operation in milliseconds */
+    duration: number;
+    /** Whether the result came from cache */
+    fromCache: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/caching/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/caching/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,CAAC;AAE5D;;GAEG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,qCAAqC;IACrC,GAAG,EAAE,MAAM,CAAC;IACZ,uBAAuB;IACvB,KAAK,EAAE,CAAC,CAAC;IACT,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAC;IAChB,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;IACnB,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAC;IACnB,0DAA0D;IAC1D,cAAc,EAAE,cAAc,CAAC;IAC/B,iDAAiD;IACjD,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,IAAI,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,iDAAiD;IACjD,IAAI,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,0CAA0C;IAC1C,aAAa,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,kDAAkD;IAClD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,sCAAsC;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,CAAC,CAAC;IACV,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,SAAS,EAAE,OAAO,CAAC;CACpB"}

package/dist/chunking/chunker.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Text Chunker - Split large documents into manageable chunks
+ *
+ * Provides multiple chunking strategies for different content types:
+ * - Fixed: Simple character-based chunking with overlap
+ * - Semantic: Paragraph-based chunking respecting natural boundaries
+ * - Markdown: Respects markdown structure (headers, sections)
+ * - Code: Preserves code blocks and structure
+ * - Adaptive: Auto-selects the best strategy based on content
+ *
+ * @module chunking/chunker
+ */
+import type { ChunkOptions, ChunkResult, ChunkerConfig } from './types.js';
+/**
+ * Text Chunker class
+ *
+ * Splits documents into chunks using various strategies.
+ * Maintains document structure and provides metadata for each chunk.
+ */
+export declare class Chunker {
+    private config;
+    private defaultOptions;
+    constructor(config?: Partial<ChunkerConfig>);
+    /**
+     * Chunk content using the specified or default strategy
+     *
+     * @param content - The content to chunk
+     * @param options - Chunking options
+     * @returns ChunkResult with all chunks and metadata
+     */
+    chunk(content: string, options?: Partial<ChunkOptions>): ChunkResult;
+    /**
+     * Fixed-size chunking with optional overlap
+     *
+     * Simple character-based chunking. Best for uniform content
+     * where structure doesn't matter.
+     */
+    private chunkFixed;
+    /**
+     * Semantic chunking based on paragraph boundaries
+     *
+     * Respects natural paragraph breaks (double newlines).
+     * Groups paragraphs until maxSize is reached.
+     */
+    private chunkSemantic;
+    /**
+     * Markdown-aware chunking
+     *
+     * Respects markdown header structure. Each major section
+     * becomes its own chunk when possible.
+     */
+    private chunkMarkdown;
+    /**
+     * Code-aware chunking
+     *
+     * Preserves code blocks (fenced with ```) as atomic units.
+     * Non-code sections are chunked semantically.
+     */
+    private chunkCode;
+    /**
+     * Adaptive chunking - auto-selects best strategy
+     *
+     * Analyzes content to determine the best chunking strategy:
+     * - Code blocks present -> code strategy
+     * - Markdown headers present -> markdown strategy
+     * - Default -> semantic strategy
+     */
+    private chunkAdaptive;
+    /**
+     * Create a chunk object with metadata
+     */
+    private createChunk;
+    /**
+     * Detect content type from the content itself
+     */
+    private detectType;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): ChunkerConfig;
+    /**
+     * Update configuration
+     */
+    setConfig(config: Partial<ChunkerConfig>): void;
+}
+/**
+ * Create a new Chunker instance with optional configuration
+ */
+export declare function createChunker(config?: Partial<ChunkerConfig>): Chunker;
+/**
+ * Convenience function to chunk a document without creating a Chunker instance
+ */
+export declare function chunkDocument(content: string, options?: Partial<ChunkOptions>): ChunkResult;
+//# sourceMappingURL=chunker.d.ts.map

package/dist/chunking/chunker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chunker.d.ts","sourceRoot":"","sources":["../../src/chunking/chunker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EACV,YAAY,EAGZ,WAAW,EACX,aAAa,EACd,MAAM,YAAY,CAAC;AAapB;;;;;GAKG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,MAAM,CAAgB;IAC9B,OAAO,CAAC,cAAc,CAAe;gBAEzB,MAAM,GAAE,OAAO,CAAC,aAAa,CAAM;IAW/C;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,WAAW;IAqDpE;;;;;OAKG;IACH,OAAO,CAAC,UAAU;IAwBlB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IAmCrB;;;;;OAKG;IACH,OAAO,CAAC,aAAa;IA4CrB;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IAoDjB;;;;;;;OAOG;IACH,OAAO,CAAC,aAAa;IAkBrB;;OAEG;IACH,OAAO,CAAC,WAAW;IA+BnB;;OAEG;IACH,OAAO,CAAC,UAAU;IA4BlB;;OAEG;IACH,SAAS,IAAI,aAAa;IAI1B;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,IAAI;CAShD;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,aAAa,CAAC,GAAG,OAAO,CAEtE;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,GAAG,WAAW,CAG3F"}