@gotza02/seq-thinking 1.1.0

package/dist/utils/index.js

@@ -0,0 +1,864 @@
+/**
+ * Utility Functions for MCP Sequential Thinking System
+ * @module utils
+ * @version 1.0.0
+ */
+import { v4 as uuidv4 } from 'uuid';
+// ============================================================================
+// ID Generation
+// ============================================================================
+/**
+ * Generate a unique ID based on timestamp and random string
+ * @returns Unique ID string
+ */
+export function generateId() {
+    const timestamp = Date.now().toString();
+    const random = Math.random().toString(36).substring(2, 9).padEnd(7, '0');
+    return `${timestamp}-${random}`;
+}
+/**
+ * Generate a UUID v4
+ * @returns UUID string
+ */
+export function generateUUID() {
+    return uuidv4();
+}
+/**
+ * Generate a short 8-character ID
+ * @returns Short ID string
+ */
+export function generateShortId() {
+    return Math.random().toString(36).substring(2, 10);
+}
+// ============================================================================
+// Numeric Utilities
+// ============================================================================
+/**
+ * Clamp a value between min and max
+ * @param value - Value to clamp
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns Clamped value
+ */
+export function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/**
+ * Clamp a confidence score to [0, 1]
+ * @param confidence - Confidence score
+ * @returns Clamped confidence
+ */
+export function clampConfidence(confidence) {
+    return clamp(confidence, 0, 1);
+}
+/**
+ * Linear interpolation between two values
+ * @param a - Start value
+ * @param b - End value
+ * @param t - Interpolation factor (0-1)
+ * @returns Interpolated value
+ */
+export function lerp(a, b, t) {
+    return a + (b - a) * clamp(t, 0, 1);
+}
+/**
+ * Round a number to specified decimal places
+ * @param value - Value to round
+ * @param decimals - Number of decimal places
+ * @returns Rounded value
+ */
+export function roundTo(value, decimals) {
+    const factor = Math.pow(10, decimals);
+    return Math.round(value * factor) / factor;
+}
+// ============================================================================
+// Similarity Calculation
+// ============================================================================
+/**
+ * Extract words from text
+ * @param text - Input text
+ * @returns Array of words
+ */
+export function extractWords(text) {
+    return text.toLowerCase().match(/\b\w+\b/g) || [];
+}
+/**
+ * Calculate Jaccard similarity between two sets
+ * @param setA - First set
+ * @param setB - Second set
+ * @returns Jaccard similarity (0-1)
+ */
+export function calculateJaccardSimilarity(setA, setB) {
+    const intersection = new Set([...setA].filter(x => setB.has(x)));
+    const union = new Set([...setA, ...setB]);
+    return union.size === 0 ? 0 : intersection.size / union.size;
+}
+/**
+ * Calculate Levenshtein distance between two strings
+ * @param a - First string
+ * @param b - Second string
+ * @returns Levenshtein distance
+ */
+export function levenshteinDistance(a, b) {
+    const matrix = [];
+    for (let i = 0; i <= b.length; i++) {
+        matrix[i] = [i];
+    }
+    for (let j = 0; j <= a.length; j++) {
+        matrix[0][j] = j;
+    }
+    for (let i = 1; i <= b.length; i++) {
+        for (let j = 1; j <= a.length; j++) {
+            if (b.charAt(i - 1) === a.charAt(j - 1)) {
+                matrix[i][j] = matrix[i - 1][j - 1];
+            }
+            else {
+                matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // substitution
+                matrix[i][j - 1] + 1, // insertion
+                matrix[i - 1][j] + 1 // deletion
+                );
+            }
+        }
+    }
+    return matrix[b.length][a.length];
+}
+/**
+ * Calculate text similarity using Levenshtein distance
+ * @param a - First text
+ * @param b - Second text
+ * @returns Similarity score (0-1)
+ */
+export function calculateSimilarity(a, b) {
+    if (a === b)
+        return 1;
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    // Optimization: return 0 if no common characters
+    const setA = new Set(a.split(''));
+    const hasCommon = b.split('').some(char => setA.has(char));
+    if (!hasCommon)
+        return 0;
+    const distance = levenshteinDistance(a, b);
+    const longestLength = Math.max(a.length, b.length);
+    return (longestLength - distance) / longestLength;
+}
+/**
+ * Calculate cosine similarity between two vectors
+ * @param a - First vector
+ * @param b - Second vector
+ * @returns Cosine similarity (-1 to 1)
+ */
+export function calculateCosineSimilarity(a, b) {
+    if (a.length !== b.length) {
+        throw new Error('Vectors must have same length');
+    }
+    let dotProduct = 0;
+    let normA = 0;
+    let normB = 0;
+    for (let i = 0; i < a.length; i++) {
+        dotProduct += a[i] * b[i];
+        normA += a[i] * a[i];
+        normB += b[i] * b[i];
+    }
+    if (normA === 0 || normB === 0) {
+        return 0;
+    }
+    return dotProduct / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+/**
+ * Extract n-grams from text
+ * @param text - Input text
+ * @param n - N-gram size
+ * @returns Array of n-grams
+ */
+export function extractNGrams(text, n) {
+    const words = extractWords(text);
+    const ngrams = [];
+    for (let i = 0; i <= words.length - n; i++) {
+        ngrams.push(words.slice(i, i + n).join(' '));
+    }
+    return ngrams;
+}
+/**
+ * Calculate n-gram similarity between two texts
+ * @param a - First text
+ * @param b - Second text
+ * @param n - N-gram size (default: 2)
+ * @returns Similarity score (0-1)
+ */
+export function calculateNGramSimilarity(a, b, n = 2) {
+    const ngramsA = new Set(extractNGrams(a, n));
+    const ngramsB = new Set(extractNGrams(b, n));
+    return calculateJaccardSimilarity(ngramsA, ngramsB);
+}
+// ============================================================================
+// Statistical Utilities
+// ============================================================================
+/**
+ * Calculate mean of an array of numbers
+ * @param values - Array of numbers
+ * @returns Mean value
+ */
+export function calculateMean(values) {
+    if (values.length === 0)
+        return NaN;
+    return values.reduce((sum, v) => sum + v, 0) / values.length;
+}
+/**
+ * Calculate weighted average
+ * @param values - Array of values
+ * @param weights - Array of weights
+ * @returns Weighted average
+ */
+export function calculateWeightedAverage(values, weights) {
+    if (values.length !== weights.length) {
+        throw new Error('Values and weights must have same length');
+    }
+    if (values.length === 0)
+        return NaN;
+    const totalWeight = weights.reduce((sum, w) => sum + w, 0);
+    if (totalWeight === 0)
+        return 0;
+    const weightedSum = values.reduce((sum, v, i) => sum + v * weights[i], 0);
+    return weightedSum / totalWeight;
+}
+/**
+ * Calculate median of an array of numbers
+ * @param values - Array of numbers
+ * @returns Median value
+ */
+export function calculateMedian(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return (sorted[mid - 1] + sorted[mid]) / 2;
+    }
+    return sorted[mid];
+}
+/**
+ * Calculate standard deviation
+ * @param values - Array of numbers
+ * @returns Standard deviation
+ */
+export function calculateStandardDeviation(values) {
+    if (values.length === 0)
+        return 0;
+    const mean = calculateMean(values);
+    const squaredDiffs = values.map(v => Math.pow(v - mean, 2));
+    const variance = calculateMean(squaredDiffs);
+    return Math.sqrt(variance);
+}
+/**
+ * Calculate variance
+ * @param values - Array of numbers
+ * @returns Variance
+ */
+export function calculateVariance(values) {
+    if (values.length === 0)
+        return 0;
+    const mean = calculateMean(values);
+    const squaredDiffs = values.map(v => Math.pow(v - mean, 2));
+    return calculateMean(squaredDiffs);
+}
+/**
+ * Find minimum value
+ * @param values - Array of numbers
+ * @returns Minimum value
+ */
+export function findMin(values) {
+    if (values.length === 0)
+        return 0;
+    return Math.min(...values);
+}
+/**
+ * Find maximum value
+ * @param values - Array of numbers
+ * @returns Maximum value
+ */
+export function findMax(values) {
+    if (values.length === 0)
+        return 0;
+    return Math.max(...values);
+}
+/**
+ * Normalize values to [0, 1] range
+ * @param values - Array of numbers
+ * @returns Normalized values
+ */
+export function normalizeValues(values) {
+    if (values.length === 0)
+        return [];
+    const min = findMin(values);
+    const max = findMax(values);
+    const range = max - min;
+    if (range === 0)
+        return values.map(() => 0.5);
+    return values.map(v => (v - min) / range);
+}
+/**
+ * Calculate percentile
+ * @param values - Array of numbers
+ * @param percentile - Percentile (0-100)
+ * @returns Percentile value
+ */
+export function calculatePercentile(values, percentile) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const index = (percentile / 100) * (sorted.length - 1);
+    const lower = Math.floor(index);
+    const upper = Math.ceil(index);
+    const weight = index - lower;
+    return sorted[lower] * (1 - weight) + sorted[upper] * weight;
+}
+// ============================================================================
+// Time Formatting
+// ============================================================================
+/**
+ * Format duration in milliseconds to human-readable string
+ * @param ms - Duration in milliseconds
+ * @returns Formatted string
+ */
+export function formatDuration(ms) {
+    const isNegative = ms < 0;
+    const absMs = Math.abs(Math.floor(ms));
+    const sign = isNegative ? '-' : '';
+    if (absMs < 1000) {
+        return `${sign}${absMs}ms`;
+    }
+    const seconds = Math.floor(absMs / 1000);
+    if (seconds < 60) {
+        return `${sign}${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        return `${sign}${minutes}m`;
+    }
+    const hours = Math.floor(minutes / 60);
+    return `${sign}${hours}h`;
+}
+/**
+ * Format timestamp to ISO string
+ * @param timestamp - Timestamp (Date or number)
+ * @returns ISO string
+ */
+export function formatTimestamp(timestamp) {
+    const date = timestamp instanceof Date ? timestamp : new Date(timestamp);
+    return date.toISOString();
+}
+/**
+ * Format relative time (e.g., "2m ago")
+ * @param timestamp - Timestamp (Date or number)
+ * @returns Relative time string
+ */
+export function formatRelativeTime(timestamp) {
+    const date = timestamp instanceof Date ? timestamp : new Date(timestamp);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const seconds = Math.floor(diffMs / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    const days = Math.floor(hours / 24);
+    if (days > 0)
+        return `${days}d ago`;
+    if (hours > 0)
+        return `${hours}h ago`;
+    if (minutes > 0)
+        return `${minutes}m ago`;
+    return `${seconds}s ago`;
+}
+// ============================================================================
+// Object Utilities
+// ============================================================================
+/**
+ * Deep clone an object
+ * @param obj - Object to clone
+ * @returns Cloned object
+ */
+export function deepClone(obj) {
+    if (obj === null || typeof obj !== 'object')
+        return obj;
+    if (obj instanceof Date)
+        return new Date(obj.getTime());
+    if (Array.isArray(obj))
+        return obj.map(deepClone);
+    const cloned = {};
+    for (const key in obj) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            cloned[key] = deepClone(obj[key]);
+        }
+    }
+    return cloned;
+}
+/**
+ * Deep clone with Date support
+ * @param obj - Object to clone
+ * @returns Cloned object with Dates preserved
+ */
+export function deepCloneWithDates(obj) {
+    return deepClone(obj);
+}
+/**
+ * Deep merge two objects
+ * @param target - Target object
+ * @param source - Source object
+ * @returns Merged object
+ */
+export function deepMerge(target, source) {
+    const result = { ...target };
+    for (const key in source) {
+        if (Object.prototype.hasOwnProperty.call(source, key)) {
+            const sourceValue = source[key];
+            const targetValue = result[key];
+            if (typeof sourceValue === 'object' &&
+                sourceValue !== null &&
+                !Array.isArray(sourceValue) &&
+                typeof targetValue === 'object' &&
+                targetValue !== null &&
+                !Array.isArray(targetValue)) {
+                result[key] = deepMerge(targetValue, sourceValue);
+            }
+            else {
+                result[key] = sourceValue;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Deep equality check
+ * @param a - First object
+ * @param b - Second object
+ * @returns True if equal
+ */
+export function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return false;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    if (a instanceof Date && b instanceof Date) {
+        return a.getTime() === b.getTime();
+    }
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((item, i) => deepEqual(item, b[i]));
+    }
+    const aObj = a;
+    const bObj = b;
+    const aKeys = Object.keys(aObj);
+    const bKeys = Object.keys(bObj);
+    if (aKeys.length !== bKeys.length)
+        return false;
+    return aKeys.every(key => deepEqual(aObj[key], bObj[key]));
+}
+/**
+ * Pick specific keys from an object
+ * @param obj - Source object
+ * @param keys - Keys to pick
+ * @returns Object with picked keys
+ */
+export function pick(obj, keys) {
+    const result = {};
+    for (const key of keys) {
+        if (Object.prototype.hasOwnProperty.call(obj, key)) {
+            result[key] = obj[key];
+        }
+    }
+    return result;
+}
+/**
+ * Omit specific keys from an object
+ * @param obj - Source object
+ * @param keys - Keys to omit
+ * @returns Object without omitted keys
+ */
+export function omit(obj, keys) {
+    const result = { ...obj };
+    for (const key of keys) {
+        delete result[key];
+    }
+    return result;
+}
+// ============================================================================
+// Validation Utilities
+// ============================================================================
+/**
+ * Validate UUID format
+ * @param uuid - String to validate
+ * @returns True if valid UUID
+ */
+export function validateUUID(uuid) {
+    const uuidRegex = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+    return uuidRegex.test(uuid);
+}
+/**
+ * Check if value is a non-empty string
+ * @param value - Value to check
+ * @returns True if non-empty string
+ */
+export function isNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0;
+}
+/**
+ * Check if value is a positive number
+ * @param value - Value to check
+ * @returns True if positive number
+ */
+export function isPositiveNumber(value) {
+    return typeof value === 'number' && !isNaN(value) && value > 0;
+}
+/**
+ * Check if value is in range
+ * @param value - Value to check
+ * @param min - Minimum value
+ * @param max - Maximum value
+ * @returns True if in range
+ */
+export function isInRange(value, min, max) {
+    return value >= min && value <= max;
+}
+/**
+ * Check if value is a non-empty array
+ * @param value - Value to check
+ * @returns True if non-empty array
+ */
+export function isNonEmptyArray(value) {
+    return Array.isArray(value) && value.length > 0;
+}
+/**
+ * Check if value is a plain object
+ * @param value - Value to check
+ * @returns True if plain object
+ */
+export function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+// ============================================================================
+// String Utilities
+// ============================================================================
+/**
+ * Sanitize input string (remove special characters)
+ * @param input - Input string
+ * @returns Sanitized string
+ */
+export function sanitizeString(input) {
+    return input.replace(/[<>\"']/g, '');
+}
+/**
+ * Truncate string with ellipsis
+ * @param str - String to truncate
+ * @param maxLength - Maximum length
+ * @returns Truncated string
+ */
+export function truncateString(str, maxLength) {
+    if (str.length <= maxLength)
+        return str;
+    return str.substring(0, maxLength - 3) + '...';
+}
+/**
+ * Convert string to camelCase
+ * @param str - Input string
+ * @returns camelCase string
+ */
+export function toCamelCase(str) {
+    return str
+        .replace(/(?:^\w|[A-Z]|\b\w)/g, (word, index) => index === 0 ? word.toLowerCase() : word.toUpperCase())
+        .replace(/\s+/g, '');
+}
+/**
+ * Convert string to PascalCase
+ * @param str - Input string
+ * @returns PascalCase string
+ */
+export function toPascalCase(str) {
+    return str
+        .replace(/(?:^\w|[A-Z]|\b\w)/g, word => word.toUpperCase())
+        .replace(/\s+/g, '');
+}
+/**
+ * Convert string to snake_case
+ * @param str - Input string
+ * @returns snake_case string
+ */
+export function toSnakeCase(str) {
+    return str
+        .replace(/\W+/g, ' ')
+        .split(/ |\B(?=[A-Z])/)
+        .map(word => word.toLowerCase())
+        .join('_');
+}
+/**
+ * Convert string to kebab-case
+ * @param str - Input string
+ * @returns kebab-case string
+ */
+export function toKebabCase(str) {
+    return str
+        .replace(/\W+/g, ' ')
+        .split(/ |\B(?=[A-Z])/)
+        .map(word => word.toLowerCase())
+        .join('-');
+}
+/**
+ * Escape regex special characters
+ * @param str - Input string
+ * @returns Escaped string
+ */
+export function escapeRegExp(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+// ============================================================================
+// Array Utilities
+// ============================================================================
+/**
+ * Remove duplicates from array
+ * @param arr - Input array
+ * @returns Array without duplicates
+ */
+export function unique(arr) {
+    return [...new Set(arr)];
+}
+/**
+ * Remove duplicates by key function
+ * @param arr - Input array
+ * @param keyFn - Key function
+ * @returns Array without duplicates
+ */
+export function uniqueBy(arr, keyFn) {
+    const seen = new Set();
+    return arr.filter(item => {
+        const key = keyFn(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+/**
+ * Group array by key function
+ * @param arr - Input array
+ * @param keyFn - Key function
+ * @returns Grouped object
+ */
+export function groupBy(arr, keyFn) {
+    return arr.reduce((groups, item) => {
+        const key = keyFn(item);
+        if (!groups[key])
+            groups[key] = [];
+        groups[key].push(item);
+        return groups;
+    }, {});
+}
+/**
+ * Partition array by predicate
+ * @param arr - Input array
+ * @param predicate - Predicate function
+ * @returns [passing, failing] arrays
+ */
+export function partition(arr, predicate) {
+    const passing = [];
+    const failing = [];
+    for (const item of arr) {
+        if (predicate(item)) {
+            passing.push(item);
+        }
+        else {
+            failing.push(item);
+        }
+    }
+    return [passing, failing];
+}
+/**
+ * Shuffle array (Fisher-Yates algorithm)
+ * @param arr - Input array
+ * @returns Shuffled array
+ */
+export function shuffle(arr) {
+    const result = [...arr];
+    for (let i = result.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}
+/**
+ * Sample random element from array
+ * @param arr - Input array
+ * @returns Random element
+ */
+export function sample(arr) {
+    if (arr.length === 0)
+        return undefined;
+    return arr[Math.floor(Math.random() * arr.length)];
+}
+/**
+ * Split array into chunks
+ * @param arr - Input array
+ * @param size - Chunk size
+ * @returns Array of chunks
+ */
+export function chunk(arr, size) {
+    const result = [];
+    for (let i = 0; i < arr.length; i += size) {
+        result.push(arr.slice(i, i + size));
+    }
+    return result;
+}
+/**
+ * Flatten array one level
+ * @param arr - Input array
+ * @returns Flattened array
+ */
+export function flatten(arr) {
+    return arr.reduce((flat, item) => flat.concat(item), []);
+}
+/**
+ * Deep flatten array
+ * @param arr - Input array
+ * @returns Deeply flattened array
+ */
+export function deepFlatten(arr) {
+    const result = [];
+    for (const item of arr) {
+        if (Array.isArray(item)) {
+            result.push(...deepFlatten(item));
+        }
+        else {
+            result.push(item);
+        }
+    }
+    return result;
+}
+// ============================================================================
+// Async Utilities
+// ============================================================================
+/**
+ * Sleep for specified milliseconds
+ * @param ms - Milliseconds to sleep
+ * @returns Promise that resolves after ms
+ */
+export function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Create a timeout promise
+ * @param ms - Timeout in milliseconds
+ * @param message - Error message
+ * @returns Promise that rejects after ms
+ */
+export function createTimeoutPromise(ms, message = 'Operation timed out') {
+    return new Promise((_, reject) => {
+        setTimeout(() => reject(new Error(message)), ms);
+    });
+}
+/**
+ * Wrap promise with timeout
+ * @param promise - Promise to wrap
+ * @param ms - Timeout in milliseconds
+ * @returns Promise with timeout
+ */
+export async function withTimeout(promise, ms) {
+    return Promise.race([promise, createTimeoutPromise(ms)]);
+}
+/**
+ * Retry a function with exponential backoff
+ * @param fn - Function to retry
+ * @param maxRetries - Maximum retries
+ * @param delayMs - Initial delay
+ * @returns Function result
+ */
+export async function retry(fn, maxRetries = 3, delayMs = 1000) {
+    let lastError;
+    for (let i = 0; i < maxRetries; i++) {
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error instanceof Error ? error : new Error(String(error));
+            if (i < maxRetries - 1) {
+                await sleep(delayMs * Math.pow(2, i));
+            }
+        }
+    }
+    throw lastError || new Error('Retry failed');
+}
+/**
+ * Debounce a function
+ * @param fn - Function to debounce
+ * @param ms - Debounce delay
+ * @returns Debounced function
+ */
+export function debounce(fn, ms) {
+    let timeoutId = null;
+    return (...args) => {
+        if (timeoutId)
+            clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => fn(...args), ms);
+    };
+}
+/**
+ * Throttle a function
+ * @param fn - Function to throttle
+ * @param ms - Throttle interval
+ * @returns Throttled function
+ */
+export function throttle(fn, ms) {
+    let lastTime = 0;
+    return (...args) => {
+        const now = Date.now();
+        if (now - lastTime >= ms) {
+            lastTime = now;
+            fn(...args);
+        }
+    };
+}
+// ============================================================================
+// Error Handling
+// ============================================================================
+/**
+ * Try-catch wrapper for synchronous functions
+ * @param fn - Function to wrap
+ * @returns Result object
+ */
+export function tryCatch(fn) {
+    try {
+        return { success: true, data: fn() };
+    }
+    catch (error) {
+        return { success: false, error: error };
+    }
+}
+/**
+ * Try-catch wrapper for async functions
+ * @param fn - Async function to wrap
+ * @returns Result object
+ */
+export async function tryCatchAsync(fn) {
+    try {
+        return { success: true, data: await fn() };
+    }
+    catch (error) {
+        return { success: false, error: error };
+    }
+}
+/**
+ * Create enhanced error with context
+ * @param message - Error message
+ * @param context - Error context
+ * @returns Enhanced error
+ */
+export function createError(message, context) {
+    const error = new Error(message);
+    if (context) {
+        error.context = context;
+    }
+    return error;
+}
+//# sourceMappingURL=index.js.map