/** * String Helpers * * Generic string manipulation utilities used across the framework. * * @module utils/string-helpers */ // ============================================================================ // Comma-Separated Parsing // ============================================================================ /** * Split a comma-separated string into trimmed, non-empty segments. * * Used by Zod schema helpers and config file mappers to provide * a single source of truth for CSV-style string parsing. * * @param value - Raw comma-separated string (e.g., `"a, b, c"`) * @param options - Parsing options * @param options.lowercase - Lowercase all segments (default: false) * @returns Array of trimmed, non-empty strings * * @example * ```typescript * splitCommaSeparated('a, b, c'); // ['a', 'b', 'c'] * splitCommaSeparated('A, B', { lowercase: true }); // ['a', 'b'] * splitCommaSeparated(''); // [] * splitCommaSeparated(' , , '); // [] * ``` */ export function splitCommaSeparated(value: string, options: { lowercase?: boolean } = {}): string[] { const items = value .split(",") .map((s) => s.trim()) .filter((s) => s.length > 0); return options.lowercase ? items.map((s) => s.toLowerCase()) : items; } // ============================================================================ // Template Interpolation // ============================================================================ /** * Cached regex for template interpolation. * Pattern matches `{variableName}` placeholders. */ const INTERPOLATION_REGEX = /\{(\w+)\}/g; /** * Interpolation parameters type. * Maps template variable names to their values. */ export type MessageParams = Record; /** * Interpolate a template string with parameters. * * Replaces `{variableName}` placeholders with values from the params object. * Unmatched placeholders are preserved as-is. * * @param template - The template string with `{variable}` placeholders * @param params - The parameters to interpolate * @returns The interpolated string * * @example * ```typescript * interpolate("Hello {name}!", { name: "World" }) * // "Hello World!" * ``` */ export function interpolate(template: string, params: MessageParams): string { INTERPOLATION_REGEX.lastIndex = 0; return template.replace(INTERPOLATION_REGEX, (match, key: string) => { const value = params[key]; if (value === undefined) { return match; } return String(value); }); } // ============================================================================ // ID Truncation // ============================================================================ /** Default display length for truncated IDs. */ const DEFAULT_ID_DISPLAY_LENGTH = 8; /** * Truncate an ID string (session, request, trace) for display purposes. * * Keeps logs readable while providing enough uniqueness for debugging. * Also avoids exposing full tokens in log output. * * @param id - The full ID string * @param length - Number of characters to keep (default: 8) * @returns Truncated ID * * @example * ```typescript * truncateId('a1b2c3d4-e5f6-7890-abcd-ef1234567890') * // Returns: 'a1b2c3d4' * ``` */ export function truncateId(id: string, length = DEFAULT_ID_DISPLAY_LENGTH): string { return id.substring(0, length); } // ============================================================================ // Byte Size Parsing // ============================================================================ /** * Regex pattern for human-readable byte sizes. * * Matches formats like `"10mb"`, `"1.5gb"`, `"500kb"`, or plain byte * counts like `"1048576"`. Case-insensitive, optional whitespace * between number and unit. * * Shared with Zod schemas (`MCP_BODY_SIZE_LIMIT`, `LOG_MAX_FILE_SIZE`) * to ensure consistent validation across env vars and config files. * * @example * ```typescript * BYTE_SIZE_REGEX.test('10mb'); // true * BYTE_SIZE_REGEX.test('1.5 gb'); // true * BYTE_SIZE_REGEX.test('1048576'); // true (plain bytes) * BYTE_SIZE_REGEX.test('abc'); // false * ``` */ // eslint-disable-next-line security/detect-unsafe-regex -- linear-time (no ambiguous nesting); only ever tested against trusted config/env values. export const BYTE_SIZE_REGEX = /^\d+(\.\d+)?\s*(kb|mb|gb|tb|pb)?$/i; /** * Binary unit multipliers (1 KB = 1024 bytes). * @internal */ const BYTE_MULTIPLIERS: Readonly> = { kb: 1024, mb: 1024 ** 2, gb: 1024 ** 3, tb: 1024 ** 4, pb: 1024 ** 5, }; /** * Parse a human-readable byte size string into a number of bytes. * * Accepts formats like `"10mb"`, `"1.5gb"`, `"500kb"`, or plain numeric * strings like `"1048576"` (interpreted as bytes). Uses binary units * (1 KB = 1024 bytes, 1 MB = 1048576 bytes, etc.). * * The supported units match the `MCP_BODY_SIZE_LIMIT` regex pattern * used throughout the framework: `kb`, `mb`, `gb`, `tb`, `pb`. * * @param value - Human-readable size string (e.g. `"10mb"`, `"1048576"`) * @returns Number of bytes (floored to integer) * @throws {Error} If the format is invalid * * @example * ```typescript * parseByteSize('10mb'); // 10485760 * parseByteSize('500kb'); // 512000 * parseByteSize('1.5gb'); // 1610612736 * parseByteSize('1048576'); // 1048576 (plain bytes) * ``` */ export function parseByteSize(value: string): number { const trimmed = value.trim(); // eslint-disable-next-line security/detect-unsafe-regex -- linear-time; input is a trusted config/env size string. const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*(kb|mb|gb|tb|pb)?$/i); if (!match) { throw new Error( `Invalid byte size format: "${value}". Use formats like "10mb", "500kb", "2gb", or a plain byte count like "1048576".`, ); } // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- group 1 is required, always present on a match. const num = parseFloat(match[1]!); const unit = match[2]?.toLowerCase(); if (!unit) { return Math.floor(num); } return Math.floor(num * (BYTE_MULTIPLIERS[unit] ?? 1)); } // ============================================================================ // Duration Parsing // ============================================================================ /** * Duration unit multipliers (all units → milliseconds). * * Each canonical unit accepts friendly aliases so config values can read naturally * (`"1min"`, `"30sec"`, `"2hrs"`) as well as the short forms (`"1m"`, `"30s"`, `"2h"`). * @internal */ const DURATION_MULTIPLIERS: Readonly> = { ms: 1, msec: 1, msecs: 1, millisecond: 1, milliseconds: 1, s: 1_000, sec: 1_000, secs: 1_000, second: 1_000, seconds: 1_000, m: 60_000, min: 60_000, mins: 60_000, minute: 60_000, minutes: 60_000, h: 3_600_000, hr: 3_600_000, hrs: 3_600_000, hour: 3_600_000, hours: 3_600_000, d: 86_400_000, day: 86_400_000, days: 86_400_000, w: 604_800_000, week: 604_800_000, weeks: 604_800_000, }; /** * Duration unit alternation for the parsing/validation regexes — longest aliases first so * `min`/`ms` win over `m`/`s`. Built once from {@link DURATION_MULTIPLIERS} so the accepted * units stay a single source of truth. Every element is a static, code-controlled literal * (never user input), so the composed regexes are safe. * @internal */ const DURATION_UNIT_PATTERN = Object.keys(DURATION_MULTIPLIERS) .sort((a, b) => b.length - a.length) .join("|"); /** * Regex pattern for human-readable durations. * * Matches formats like `"15m"`, `"1.5h"`, `"500ms"`, `"1min"`, `"2hrs"`, or plain * millisecond counts like `"900000"`. Case-insensitive, optional whitespace between * number and unit. * * Shared with Zod schemas (`MCP_RATE_LIMIT_WINDOW_MS`, `OTEL_METRIC_EXPORT_INTERVAL`) * to ensure consistent validation across env vars and config files. * * @example * ```typescript * DURATION_REGEX.test('15m'); // true * DURATION_REGEX.test('1.5 h'); // true * DURATION_REGEX.test('1min'); // true * DURATION_REGEX.test('900000'); // true (plain ms) * DURATION_REGEX.test('abc'); // false * ``` */ // eslint-disable-next-line security/detect-non-literal-regexp -- pattern built from a static, code-controlled unit allowlist (DURATION_MULTIPLIERS keys), never user input; linear-time. export const DURATION_REGEX = new RegExp(`^\\d+(\\.\\d+)?\\s*(${DURATION_UNIT_PATTERN})?$`, "i"); /** Capturing variant of {@link DURATION_REGEX} — group 1 = number, group 2 = unit. @internal */ // eslint-disable-next-line security/detect-non-literal-regexp -- same static unit allowlist as DURATION_REGEX; never user input; linear-time. const DURATION_PARSE_REGEX = new RegExp(`^(\\d+(?:\\.\\d+)?)\\s*(${DURATION_UNIT_PATTERN})?$`, "i"); /** * Parse a human-readable duration string into milliseconds. * * Accepts formats like `"15m"`, `"1.5h"`, `"500ms"`, `"2d"`, or plain * numeric strings like `"900000"` (interpreted as milliseconds). Each unit * also accepts friendly aliases: * * | Unit | Meaning | Aliases | Multiplier | * |------|-------------|--------------------------------|-------------| * | ms | milliseconds | msec(s), millisecond(s) | 1 | * | s | seconds | sec(s), second(s) | 1,000 | * | m | minutes | min(s), minute(s) | 60,000 | * | h | hours | hr(s), hour(s) | 3,600,000 | * | d | days | day(s) | 86,400,000 | * | w | weeks | week(s) | 604,800,000 | * * @param value - Human-readable duration string (e.g. `"15m"`, `"1min"`, `"900000"`) * @returns Duration in milliseconds (floored to integer) * @throws {Error} If the format is invalid * * @example * ```typescript * parseDuration('15m'); // 900000 * parseDuration('1.5h'); // 5400000 * parseDuration('1min'); // 60000 * parseDuration('500ms'); // 500 * parseDuration('900000'); // 900000 (plain ms) * ``` */ export function parseDuration(value: string): number { const trimmed = value.trim(); const match = DURATION_PARSE_REGEX.exec(trimmed); if (!match) { throw new Error( `Invalid duration format: "${value}". Use formats like "15m", "1.5h", "1min", "500ms", "2d", or a plain millisecond count like "900000".`, ); } // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- group 1 is required, always present on a match. const num = parseFloat(match[1]!); const unit = match[2]?.toLowerCase(); if (!unit) { return Math.floor(num); } return Math.floor(num * (DURATION_MULTIPLIERS[unit] ?? 1)); } /** * Format milliseconds as a human-readable duration string. * * Inverse of {@link parseDuration}. Produces the most natural unit * for the given value, using at most two segments (e.g. `"1m 30s"`). * * @param ms - Duration in milliseconds * @returns Human-readable duration string * * @example * ```typescript * formatDuration(500); // "500ms" * formatDuration(5000); // "5s" * formatDuration(90_000); // "1m 30s" * formatDuration(900_000); // "15m" * formatDuration(3_600_000); // "1h" * formatDuration(86_400_000); // "1d" * ``` */ export function formatDuration(ms: number): string { if (ms < 1000) return `${ms}ms`; if (ms < 60_000) { const s = ms / 1000; return Number.isInteger(s) ? `${s}s` : `${s.toFixed(1)}s`; } if (ms < 3_600_000) { const m = Math.floor(ms / 60_000); const s = Math.round((ms % 60_000) / 1000); return s > 0 ? `${m}m ${s}s` : `${m}m`; } if (ms < 86_400_000) { const h = Math.floor(ms / 3_600_000); const m = Math.round((ms % 3_600_000) / 60_000); return m > 0 ? `${h}h ${m}m` : `${h}h`; } const d = Math.floor(ms / 86_400_000); const h = Math.round((ms % 86_400_000) / 3_600_000); return h > 0 ? `${d}d ${h}h` : `${d}d`; } // ============================================================================ // Network Helpers // ============================================================================ /** * Check if a host string is a localhost/loopback address. * * @param host - The host string to check (e.g., 'localhost:3000', '192.168.1.1') * @returns true if the host is a local loopback address * * @example * ```typescript * isLocalHost('localhost:3000'); // true * isLocalHost('127.0.0.1'); // true * isLocalHost('[::1]:8080'); // true * isLocalHost('192.168.1.1'); // false * ``` */ export function isLocalHost(host: string): boolean { const cleanHost = host.trim().toLowerCase(); return ( cleanHost.startsWith("localhost:") || cleanHost === "localhost" || cleanHost.startsWith("127.0.0.1:") || cleanHost === "127.0.0.1" || cleanHost.startsWith("[::1]:") || cleanHost === "[::1]" ); } /** * Removes trailing slash characters from a string. * * Uses a linear scan instead of regex to avoid polynomial ReDoS * on attacker-controlled input (CWE-1333). * * @example * ```typescript * stripTrailingSlashes('https://example.com/'); // 'https://example.com' * stripTrailingSlashes('https://example.com///'); // 'https://example.com' * stripTrailingSlashes('https://example.com'); // 'https://example.com' * ``` */ export function stripTrailingSlashes(str: string): string { let end = str.length; while (end > 0 && str.charCodeAt(end - 1) === 47) end--; // 47 = '/' return end === str.length ? str : str.slice(0, end); } /** * Escapes HTML special characters to prevent XSS when embedding text in HTML. * Covers the five characters that can break out of HTML attribute and text contexts. */ export function escapeHtml(s: string): string { return s .replace(/&/g, "&") .replace(//g, ">") .replace(/"/g, """) .replace(/'/g, "'"); }