@danielsimonjr/memory-mcp 9.9.0 → 10.0.0

package/dist/utils/WorkerPoolManager.js

@@ -0,0 +1,420 @@
+/**
+ * Worker Pool Manager
+ *
+ * Phase 12 Sprint 2: Unified worker pool management for all parallelizable operations.
+ * Provides centralized lifecycle management, configuration, and statistics.
+ *
+ * @module utils/WorkerPoolManager
+ */
+import workerpool from '@danielsimonjr/workerpool';
+/**
+ * Default configuration values.
+ */
+const DEFAULT_CONFIG = {
+    maxWorkers: Math.max(1, workerpool.cpus - 1),
+    workerType: 'thread',
+    workerPath: '',
+    minParallelSize: 200,
+    defaultTimeout: 30000,
+};
+/**
+ * WorkerPoolManager - Unified worker pool management
+ *
+ * Provides centralized management of worker pools for parallel processing.
+ * Features:
+ * - Named pool registration with automatic lifecycle management
+ * - Pool cleanup on process exit
+ * - Statistics tracking per pool
+ * - Event callbacks for monitoring
+ *
+ * @example
+ * ```typescript
+ * const manager = WorkerPoolManager.getInstance();
+ *
+ * // Get or create a pool
+ * const pool = manager.getPool('fuzzySearch', {
+ *   maxWorkers: 4,
+ *   workerPath: '/path/to/worker.js'
+ * });
+ *
+ * // Execute task
+ * const result = await pool.exec('searchEntities', [data]);
+ *
+ * // Get statistics
+ * const stats = manager.getPoolStats('fuzzySearch');
+ *
+ * // Shutdown all pools on exit
+ * await manager.shutdownAll();
+ * ```
+ */
+export class WorkerPoolManager {
+    static instance = null;
+    pools = new Map();
+    eventCallbacks = [];
+    isShuttingDown = false;
+    shutdownRegistered = false;
+    /**
+     * Private constructor for singleton pattern.
+     */
+    constructor() {
+        this.registerShutdownHandlers();
+    }
+    /**
+     * Get the singleton instance of WorkerPoolManager.
+     *
+     * @returns The WorkerPoolManager instance
+     */
+    static getInstance() {
+        if (!WorkerPoolManager.instance) {
+            WorkerPoolManager.instance = new WorkerPoolManager();
+        }
+        return WorkerPoolManager.instance;
+    }
+    /**
+     * Reset the singleton instance (primarily for testing).
+     */
+    static resetInstance() {
+        if (WorkerPoolManager.instance) {
+            WorkerPoolManager.instance.shutdownAll().catch(() => {
+                // Ignore errors during reset
+            });
+            WorkerPoolManager.instance = null;
+        }
+    }
+    /**
+     * Register process exit handlers for cleanup.
+     */
+    registerShutdownHandlers() {
+        if (this.shutdownRegistered)
+            return;
+        this.shutdownRegistered = true;
+        const shutdownHandler = () => {
+            if (!this.isShuttingDown) {
+                this.shutdownAllSync();
+            }
+        };
+        // Register for various exit signals
+        process.on('exit', shutdownHandler);
+        process.on('SIGINT', () => {
+            this.shutdownAll().then(() => process.exit(0)).catch(() => process.exit(1));
+        });
+        process.on('SIGTERM', () => {
+            this.shutdownAll().then(() => process.exit(0)).catch(() => process.exit(1));
+        });
+        process.on('uncaughtException', (err) => {
+            console.error('Uncaught exception:', err);
+            this.shutdownAllSync();
+            process.exit(1);
+        });
+    }
+    /**
+     * Get or create a named worker pool.
+     *
+     * If a pool with the given ID exists, returns the existing pool.
+     * Otherwise, creates a new pool with the provided configuration.
+     *
+     * @param poolId - Unique identifier for the pool
+     * @param config - Pool configuration options
+     * @returns The worker pool instance
+     */
+    getPool(poolId, config = {}) {
+        const existing = this.pools.get(poolId);
+        if (existing) {
+            return existing.pool;
+        }
+        return this.createPool(poolId, config);
+    }
+    /**
+     * Create a new worker pool with the given ID.
+     *
+     * @param poolId - Unique identifier for the pool
+     * @param config - Pool configuration options
+     * @returns The newly created worker pool
+     * @throws Error if a pool with the same ID already exists
+     */
+    createPool(poolId, config = {}) {
+        if (this.pools.has(poolId)) {
+            throw new Error(`Pool with ID '${poolId}' already exists`);
+        }
+        const mergedConfig = { ...DEFAULT_CONFIG, ...config };
+        // Create pool options with inline type definition
+        // Using inline type since WorkerPoolOptions is not directly exported
+        const poolOptions = {
+            maxWorkers: mergedConfig.maxWorkers,
+            workerType: mergedConfig.workerType,
+        };
+        // Add worker thread options for ESM support
+        if (mergedConfig.workerType === 'thread') {
+            poolOptions.workerThreadOpts = { type: 'module' };
+        }
+        // Create pool with or without worker script
+        let pool;
+        if (mergedConfig.workerPath) {
+            pool = workerpool.pool(mergedConfig.workerPath, poolOptions);
+        }
+        else {
+            pool = workerpool.pool(poolOptions);
+        }
+        const entry = {
+            pool,
+            config: mergedConfig,
+            createdAt: Date.now(),
+            totalTasksExecuted: 0,
+            totalExecutionTime: 0,
+        };
+        this.pools.set(poolId, entry);
+        this.emitEvent(poolId, 'created');
+        return pool;
+    }
+    /**
+     * Check if a pool with the given ID exists.
+     *
+     * @param poolId - Pool identifier to check
+     * @returns True if pool exists
+     */
+    hasPool(poolId) {
+        return this.pools.has(poolId);
+    }
+    /**
+     * Get the configuration for a pool.
+     *
+     * @param poolId - Pool identifier
+     * @returns Pool configuration or undefined if not found
+     */
+    getPoolConfig(poolId) {
+        const entry = this.pools.get(poolId);
+        return entry ? { ...entry.config } : undefined;
+    }
+    /**
+     * Get extended statistics for a pool.
+     *
+     * @param poolId - Pool identifier
+     * @returns Extended pool statistics or undefined if not found
+     */
+    getPoolStats(poolId) {
+        const entry = this.pools.get(poolId);
+        if (!entry)
+            return undefined;
+        const baseStats = entry.pool.stats();
+        return {
+            ...baseStats,
+            poolId,
+            createdAt: entry.createdAt,
+            totalTasksExecuted: entry.totalTasksExecuted,
+            totalExecutionTime: entry.totalExecutionTime,
+            averageExecutionTime: entry.totalTasksExecuted > 0
+                ? entry.totalExecutionTime / entry.totalTasksExecuted
+                : 0,
+        };
+    }
+    /**
+     * Get statistics for all pools.
+     *
+     * @returns Map of pool IDs to their statistics
+     */
+    getAllPoolStats() {
+        const stats = new Map();
+        for (const poolId of this.pools.keys()) {
+            const poolStats = this.getPoolStats(poolId);
+            if (poolStats) {
+                stats.set(poolId, poolStats);
+            }
+        }
+        return stats;
+    }
+    /**
+     * Record task execution for statistics tracking.
+     *
+     * @param poolId - Pool identifier
+     * @param executionTimeMs - Task execution time in milliseconds
+     */
+    recordTaskExecution(poolId, executionTimeMs) {
+        const entry = this.pools.get(poolId);
+        if (entry) {
+            entry.totalTasksExecuted++;
+            entry.totalExecutionTime += executionTimeMs;
+        }
+    }
+    /**
+     * Execute a task on a pool with automatic statistics tracking.
+     *
+     * @template T - Result type
+     * @param poolId - Pool identifier
+     * @param method - Method name to execute (for worker script pools) or inline function
+     * @param args - Arguments to pass to the method/function
+     * @param timeout - Optional timeout in milliseconds
+     * @returns Promise resolving to the task result
+     */
+    async executeTask(poolId, method, args = [], timeout) {
+        const entry = this.pools.get(poolId);
+        if (!entry) {
+            throw new Error(`Pool '${poolId}' not found`);
+        }
+        const effectiveTimeout = timeout ?? entry.config.defaultTimeout ?? DEFAULT_CONFIG.defaultTimeout;
+        const startTime = Date.now();
+        try {
+            let result;
+            if (typeof method === 'string') {
+                // Execute named method from worker script
+                result = await entry.pool.exec(method, args).timeout(effectiveTimeout);
+            }
+            else {
+                // Execute inline function
+                result = await entry.pool.exec(method, args).timeout(effectiveTimeout);
+            }
+            const executionTime = Date.now() - startTime;
+            this.recordTaskExecution(poolId, executionTime);
+            return result;
+        }
+        catch (error) {
+            const executionTime = Date.now() - startTime;
+            this.recordTaskExecution(poolId, executionTime);
+            throw error;
+        }
+    }
+    /**
+     * Shutdown a specific pool.
+     *
+     * @param poolId - Pool identifier
+     * @param force - If true, forcefully terminate workers (default: false)
+     * @returns Promise resolving when shutdown is complete
+     */
+    async shutdownPool(poolId, force = false) {
+        const entry = this.pools.get(poolId);
+        if (!entry)
+            return;
+        try {
+            await entry.pool.terminate(force);
+            this.emitEvent(poolId, 'shutdown');
+        }
+        catch (error) {
+            this.emitEvent(poolId, 'error', error);
+            throw error;
+        }
+        finally {
+            this.pools.delete(poolId);
+        }
+    }
+    /**
+     * Shutdown all pools asynchronously.
+     *
+     * @param force - If true, forcefully terminate workers (default: false)
+     * @returns Promise resolving when all pools are shut down
+     */
+    async shutdownAll(force = false) {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        const shutdownPromises = [];
+        for (const poolId of this.pools.keys()) {
+            shutdownPromises.push(this.shutdownPool(poolId, force));
+        }
+        try {
+            await Promise.allSettled(shutdownPromises);
+        }
+        finally {
+            this.pools.clear();
+            this.isShuttingDown = false;
+        }
+    }
+    /**
+     * Synchronous shutdown for process exit handlers.
+     * Forces immediate termination of all pools.
+     */
+    shutdownAllSync() {
+        if (this.isShuttingDown)
+            return;
+        this.isShuttingDown = true;
+        for (const [poolId, entry] of this.pools) {
+            try {
+                entry.pool.terminate(true);
+                this.emitEvent(poolId, 'shutdown');
+            }
+            catch {
+                // Ignore errors during sync shutdown
+            }
+        }
+        this.pools.clear();
+        this.isShuttingDown = false;
+    }
+    /**
+     * Register an event callback for pool events.
+     *
+     * @param callback - Callback function to invoke on events
+     * @returns Unsubscribe function
+     */
+    onEvent(callback) {
+        this.eventCallbacks.push(callback);
+        return () => {
+            const index = this.eventCallbacks.indexOf(callback);
+            if (index >= 0) {
+                this.eventCallbacks.splice(index, 1);
+            }
+        };
+    }
+    /**
+     * Emit an event to all registered callbacks.
+     */
+    emitEvent(poolId, event, data) {
+        for (const callback of this.eventCallbacks) {
+            try {
+                callback(poolId, event, data);
+            }
+            catch {
+                // Ignore callback errors
+            }
+        }
+    }
+    /**
+     * Get the number of active pools.
+     *
+     * @returns Number of pools currently managed
+     */
+    get poolCount() {
+        return this.pools.size;
+    }
+    /**
+     * Get all pool IDs.
+     *
+     * @returns Array of pool identifiers
+     */
+    getPoolIds() {
+        return Array.from(this.pools.keys());
+    }
+    /**
+     * Check if the minimum parallel size threshold is met.
+     *
+     * @param poolId - Pool identifier
+     * @param size - Size of the data to process
+     * @returns True if size meets or exceeds minimum threshold
+     */
+    shouldUseParallel(poolId, size) {
+        const entry = this.pools.get(poolId);
+        const minSize = entry?.config.minParallelSize ?? DEFAULT_CONFIG.minParallelSize;
+        return size >= minSize;
+    }
+    /**
+     * Get the default configuration values.
+     *
+     * @returns Copy of default configuration
+     */
+    static getDefaultConfig() {
+        return { ...DEFAULT_CONFIG };
+    }
+    /**
+     * Get the CPU count available for workers.
+     *
+     * @returns Number of CPUs
+     */
+    static getCpuCount() {
+        return workerpool.cpus;
+    }
+}
+/**
+ * Convenience function to get the WorkerPoolManager instance.
+ *
+ * @returns The WorkerPoolManager singleton
+ */
+export function getWorkerPoolManager() {
+    return WorkerPoolManager.getInstance();
+}

package/dist/utils/compressedCache.d.ts

@@ -34,6 +34,20 @@ export interface CompressedCacheOptions {
      * @default true
      */
     autoCompress?: boolean;
+    /**
+     * Minimum entry size in bytes before compression is applied.
+     * Entries smaller than this are not compressed (overhead exceeds benefit).
+     * Phase 12 Sprint 6: Adaptive compression.
+     * @default 256
+     */
+    minCompressionSize?: number;
+    /**
+     * Minimum compression ratio to keep entry compressed.
+     * If compression achieves less than this ratio, entry stays uncompressed.
+     * Phase 12 Sprint 6: Adaptive compression.
+     * @default 0.7 (30% reduction minimum)
+     */
+    minCompressionRatio?: number;
 }
 /**
  * Statistics about the cache state.
@@ -49,6 +63,8 @@ export interface CompressedCacheStats {
     memorySaved: number;
     /** Total original size of all entries in bytes */
     totalOriginalSize: number;
+    /** Total compressed size in bytes */
+    totalCompressedSize: number;
     /** Cache hit count since creation */
     hits: number;
     /** Cache miss count since creation */
@@ -57,6 +73,14 @@ export interface CompressedCacheStats {
     compressions: number;
     /** Number of decompressions performed */
     decompressions: number;
+    /** Phase 12 Sprint 6: Number of entries skipped due to size */
+    skippedSmallEntries: number;
+    /** Phase 12 Sprint 6: Number of entries skipped due to poor ratio */
+    skippedPoorRatio: number;
+    /** Phase 12 Sprint 6: Average compression ratio (0-1) */
+    avgCompressionRatio: number;
+    /** Phase 12 Sprint 6: Estimated memory usage in bytes */
+    estimatedMemoryBytes: number;
 }
 /**
  * LRU cache with automatic compression of old entries.
@@ -88,10 +112,15 @@ export declare class CompressedCache {
     private readonly maxUncompressed;
     private readonly compressionThresholdMs;
     private readonly autoCompress;
+    private readonly minCompressionSize;
+    private readonly minCompressionRatio;
     private hits;
     private misses;
     private compressions;
     private decompressions;
+    private skippedSmallEntries;
+    private skippedPoorRatio;
+    private compressionRatios;
     constructor(options?: CompressedCacheOptions);
     /**
      * Get an entity from the cache.

package/dist/utils/compressedCache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compressedCache.d.ts","sourceRoot":"","sources":["../../src/utils/compressedCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAmBhD;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IAEzB;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAEhC;;;;OAIG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,2CAA2C;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,mCAAmC;IACnC,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;IACrB,qDAAqD;IACrD,WAAW,EAAE,MAAM,CAAC;IACpB,kDAAkD;IAClD,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,yCAAyC;IACzC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;IAChD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IAGvC,OAAO,CAAC,IAAI,CAAa;IACzB,OAAO,CAAC,MAAM,CAAa;IAC3B,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,cAAc,CAAa;gBAEvB,OAAO,GAAE,sBAA2B;IAMhD;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IA6BrC;;;;;;;;OAQG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI;IAgBvC;;;;;OAKG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI7B;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;OAEG;IACH,IAAI,IAAI,gBAAgB,CAAC,MAAM,CAAC;IAIhC;;;;OAIG;IACH,QAAQ,IAAI,oBAAoB;IA+BhC;;;;;;;OAOG;IACH,kBAAkB,IAAI,MAAM;IAI5B;;;;;OAKG;IACH,OAAO,CAAC,uBAAuB;IA2D/B;;;;;;OAMG;IACH,aAAa,IAAI,MAAM;IAsBvB;;;;OAIG;IACH,cAAc,IAAI,MAAM,EAAE;IAa1B;;;;;;OAMG;IACF,OAAO,IAAI,gBAAgB,CAAC;QAC3B,IAAI,EAAE,MAAM,CAAC;QACb,UAAU,EAAE,OAAO,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,MAAM,CAAC;KACtB,CAAC;CAUH"}
+{"version":3,"file":"compressedCache.d.ts","sourceRoot":"","sources":["../../src/utils/compressedCache.ts"],"names":[],"mappings":"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"}

package/dist/utils/compressedCache.js

@@ -43,15 +43,25 @@ export class CompressedCache {
     maxUncompressed;
     compressionThresholdMs;
     autoCompress;
+    // Phase 12 Sprint 6: Adaptive compression options
+    minCompressionSize;
+    minCompressionRatio;
     // Statistics
     hits = 0;
     misses = 0;
     compressions = 0;
     decompressions = 0;
+    // Phase 12 Sprint 6: Adaptive compression stats
+    skippedSmallEntries = 0;
+    skippedPoorRatio = 0;
+    compressionRatios = [];
     constructor(options = {}) {
         this.maxUncompressed = options.maxUncompressed ?? 1000;
         this.compressionThresholdMs = options.compressionThresholdMs ?? 5 * 60 * 1000;
         this.autoCompress = options.autoCompress ?? true;
+        // Phase 12 Sprint 6: Adaptive compression defaults
+        this.minCompressionSize = options.minCompressionSize ?? 256;
+        this.minCompressionRatio = options.minCompressionRatio ?? 0.7;
     }
     /**
      * Get an entity from the cache.
@@ -156,27 +166,42 @@ export class CompressedCache {
         let uncompressed = 0;
         let memorySaved = 0;
         let totalOriginalSize = 0;
+        let totalCompressedSize = 0;
+        let estimatedMemoryBytes = 0;
         for (const entry of this._entryMap.values()) {
             totalOriginalSize += entry.originalSize;
             if (entry.compressed && entry.compressedData) {
                 compressed++;
+                totalCompressedSize += entry.compressedData.length;
+                estimatedMemoryBytes += entry.compressedData.length;
                 // Memory saved = original size - compressed size
                 memorySaved += entry.originalSize - entry.compressedData.length;
             }
             else {
                 uncompressed++;
+                estimatedMemoryBytes += entry.originalSize;
             }
         }
+        // Calculate average compression ratio
+        const avgCompressionRatio = this.compressionRatios.length > 0
+            ? this.compressionRatios.reduce((a, b) => a + b, 0) / this.compressionRatios.length
+            : 0;
         return {
             total: this._entryMap.size,
             compressed,
             uncompressed,
             memorySaved: Math.max(0, memorySaved),
             totalOriginalSize,
+            totalCompressedSize,
             hits: this.hits,
             misses: this.misses,
             compressions: this.compressions,
             decompressions: this.decompressions,
+            // Phase 12 Sprint 6: Adaptive compression stats
+            skippedSmallEntries: this.skippedSmallEntries,
+            skippedPoorRatio: this.skippedPoorRatio,
+            avgCompressionRatio,
+            estimatedMemoryBytes,
         };
     }
     /**
@@ -226,6 +251,11 @@ export class CompressedCache {
             }
             // Compress the entry
             if (entry.entity) {
+                // Phase 12 Sprint 6: Skip small entries (adaptive compression)
+                if (entry.originalSize < this.minCompressionSize) {
+                    this.skippedSmallEntries++;
+                    continue;
+                }
                 try {
                     const jsonStr = JSON.stringify(entry.entity);
                     const compressed = brotliCompressSync(Buffer.from(jsonStr, 'utf-8'), {
@@ -233,6 +263,15 @@ export class CompressedCache {
                             [constants.BROTLI_PARAM_QUALITY]: COMPRESSION_CONFIG.BROTLI_QUALITY_CACHE,
                         },
                     });
+                    // Phase 12 Sprint 6: Check compression ratio
+                    const ratio = compressed.length / entry.originalSize;
+                    if (ratio > this.minCompressionRatio) {
+                        // Compression didn't achieve enough reduction
+                        this.skippedPoorRatio++;
+                        continue;
+                    }
+                    // Track compression ratio
+                    this.compressionRatios.push(ratio);
                     entry.compressedData = compressed;
                     entry.compressed = true;
                     entry.entity = null; // Free memory

package/dist/utils/entityUtils.d.ts

@@ -11,6 +11,31 @@
  * @module utils/entityUtils
  */
 import type { Entity, KnowledgeGraph } from '../types/index.js';
+/**
+ * FNV-1a hash function for fast string hashing.
+ *
+ * This is a non-cryptographic hash function that provides good distribution
+ * for bucketing and deduplication purposes. It's optimized for speed
+ * and produces a 32-bit unsigned integer.
+ *
+ * FNV-1a has the following properties:
+ * - Fast computation (single pass through string)
+ * - Good distribution for hash table use
+ * - Deterministic output for same input
+ *
+ * @param text - The string to hash
+ * @returns A 32-bit unsigned integer hash value
+ *
+ * @example
+ * ```typescript
+ * const hash = fnv1aHash('hello');
+ * console.log(hash); // 1335831723
+ *
+ * // Use for bucketing similar entities
+ * const bucket = fnv1aHash(entity.name.toLowerCase()) % numBuckets;
+ * ```
+ */
+export declare function fnv1aHash(text: string): number;
 /**
  * Finds an entity by name in the graph.
  * Overloaded to provide type-safe returns based on throwIfNotFound parameter.

package/dist/utils/entityUtils.d.ts.map

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

package/dist/utils/entityUtils.js

@@ -14,6 +14,39 @@ import { promises as fs } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { EntityNotFoundError, FileOperationError } from './errors.js';
+// ==================== Hash Functions ====================
+/**
+ * FNV-1a hash function for fast string hashing.
+ *
+ * This is a non-cryptographic hash function that provides good distribution
+ * for bucketing and deduplication purposes. It's optimized for speed
+ * and produces a 32-bit unsigned integer.
+ *
+ * FNV-1a has the following properties:
+ * - Fast computation (single pass through string)
+ * - Good distribution for hash table use
+ * - Deterministic output for same input
+ *
+ * @param text - The string to hash
+ * @returns A 32-bit unsigned integer hash value
+ *
+ * @example
+ * ```typescript
+ * const hash = fnv1aHash('hello');
+ * console.log(hash); // 1335831723
+ *
+ * // Use for bucketing similar entities
+ * const bucket = fnv1aHash(entity.name.toLowerCase()) % numBuckets;
+ * ```
+ */
+export function fnv1aHash(text) {
+    let hash = 2166136261; // FNV offset basis
+    for (let i = 0; i < text.length; i++) {
+        hash ^= text.charCodeAt(i);
+        hash = Math.imul(hash, 16777619); // FNV prime
+    }
+    return hash >>> 0; // Convert to unsigned 32-bit integer
+}
 export function findEntityByName(graph, name, throwIfNotFound = true) {
     const entity = graph.entities.find(e => e.name === name);
     if (!entity && throwIfNotFound) {