@socketsecurity/lib 1.0.4 → 1.1.0

package/dist/stdio/stdout.d.ts

@@ -1,47 +1,143 @@
 // Get the actual stdout stream
 declare const stdout: NodeJS.WriteStream;
 /**
- * Write a line to stdout.
+ * Write a line to stdout with trailing newline.
+ *
+ * @param text - Text to write
+ * @default text ''
+ *
+ * @example
+ * ```ts
+ * writeLine('Hello, world!')
+ * writeLine() // Write empty line
+ * ```
  */
 export declare function writeLine(text?: string): void;
 /**
- * Write text to stdout without newline.
+ * Write text to stdout without adding a newline.
+ *
+ * @param text - Text to write
+ *
+ * @example
+ * ```ts
+ * write('Loading...')
+ * // Later: clear and update
+ * ```
  */
 export declare function write(text: string): void;
 /**
  * Clear the current line on stdout.
+ * Only works in TTY environments.
+ *
+ * @example
+ * ```ts
+ * write('Processing...')
+ * clearLine()
+ * write('Done!')
+ * ```
  */
 export declare function clearLine(): void;
 /**
- * Move cursor to position on stdout.
+ * Move cursor to specific position on stdout.
+ * Only works in TTY environments.
+ *
+ * @param x - Column position (0-based)
+ * @param y - Row position (0-based, optional)
+ *
+ * @example
+ * ```ts
+ * cursorTo(0) // Move to start of line
+ * cursorTo(10, 5) // Move to column 10, row 5
+ * ```
  */
-export declare function cursorTo(x: number, y?: number): void;
+export declare function cursorTo(x: number, y?: number | undefined): void;
 /**
- * Clear screen from cursor down.
+ * Clear screen from cursor position down to bottom.
+ * Only works in TTY environments.
+ *
+ * @example
+ * ```ts
+ * cursorTo(0, 5)
+ * clearScreenDown() // Clear from row 5 to bottom
+ * ```
  */
 export declare function clearScreenDown(): void;
 /**
- * Check if stdout is a TTY.
+ * Check if stdout is connected to a TTY (terminal).
+ *
+ * @returns `true` if stdout is a TTY, `false` if piped/redirected
+ *
+ * @example
+ * ```ts
+ * if (isTTY()) {
+ *   // Show interactive UI
+ * } else {
+ *   // Use simple text output
+ * }
+ * ```
  */
 export declare function isTTY(): boolean;
 /**
- * Get terminal columns for stdout.
+ * Get the number of columns (width) in the terminal.
+ *
+ * @returns Terminal width in characters
+ * @default 80
+ *
+ * @example
+ * ```ts
+ * const width = getColumns()
+ * console.log(`Terminal is ${width} characters wide`)
+ * ```
  */
 export declare function getColumns(): number;
 /**
- * Get terminal rows for stdout.
+ * Get the number of rows (height) in the terminal.
+ *
+ * @returns Terminal height in lines
+ * @default 24
+ *
+ * @example
+ * ```ts
+ * const height = getRows()
+ * console.log(`Terminal is ${height} lines tall`)
+ * ```
  */
 export declare function getRows(): number;
 /**
- * Hide cursor on stdout.
+ * Hide the cursor on stdout.
+ * Useful for cleaner output during animations.
+ *
+ * @example
+ * ```ts
+ * hideCursor()
+ * // Show animation
+ * showCursor()
+ * ```
  */
 export declare function hideCursor(): void;
 /**
- * Show cursor on stdout.
+ * Show the cursor on stdout.
+ * Should be called after `hideCursor()`.
+ *
+ * @example
+ * ```ts
+ * hideCursor()
+ * // Show animation
+ * showCursor()
+ * ```
  */
 export declare function showCursor(): void;
 /**
- * Ensure cursor is shown on exit.
+ * Register handlers to ensure cursor is shown on process exit.
+ * Prevents hidden cursor after abnormal termination.
+ * Handles SIGINT (Ctrl+C) and SIGTERM signals.
+ *
+ * @example
+ * ```ts
+ * ensureCursorOnExit()
+ * hideCursor()
+ * // Even if process crashes, cursor will be restored
+ * ```
  */
 export declare function ensureCursorOnExit(): void;
 // Export the raw stream for advanced usage

package/dist/stdio/stdout.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/stdio/stdout.ts"],
-  "sourcesContent": ["/**\n * Standard output stream utilities.\n * Provides utilities for writing to stdout with formatting and control.\n */\n\nimport { WriteStream } from 'node:tty'\n\n// Get the actual stdout stream\nconst stdout: NodeJS.WriteStream = process.stdout\n\n/**\n * Write a line to stdout.\n */\nexport function writeLine(text: string = ''): void {\n  stdout.write(`${text}\\n`)\n}\n\n/**\n * Write text to stdout without newline.\n */\nexport function write(text: string): void {\n  stdout.write(text)\n}\n\n/**\n * Clear the current line on stdout.\n */\nexport function clearLine(): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(0)\n    stdout.clearLine(0)\n  }\n}\n\n/**\n * Move cursor to position on stdout.\n */\nexport function cursorTo(x: number, y?: number): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(x, y)\n  }\n}\n\n/**\n * Clear screen from cursor down.\n */\nexport function clearScreenDown(): void {\n  if (stdout.isTTY) {\n    stdout.clearScreenDown()\n  }\n}\n\n/**\n * Check if stdout is a TTY.\n */\nexport function isTTY(): boolean {\n  return stdout.isTTY || false\n}\n\n/**\n * Get terminal columns for stdout.\n */\nexport function getColumns(): number {\n  return stdout.columns || 80\n}\n\n/**\n * Get terminal rows for stdout.\n */\nexport function getRows(): number {\n  return stdout.rows || 24\n}\n\n/**\n * Hide cursor on stdout.\n */\nexport function hideCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25l')\n  }\n}\n\n/**\n * Show cursor on stdout.\n */\nexport function showCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25h')\n  }\n}\n\n/**\n * Ensure cursor is shown on exit.\n */\nexport function ensureCursorOnExit(): void {\n  process.on('exit', showCursor)\n  process.on('SIGINT', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(130)\n  })\n  process.on('SIGTERM', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(143)\n  })\n}\n\n// Export the raw stream for advanced usage\nexport { stdout }\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,sBAA4B;AAG5B,MAAM,SAA6B,QAAQ;AAKpC,SAAS,UAAU,OAAe,IAAU;AACjD,SAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAC1B;AAKO,SAAS,MAAM,MAAoB;AACxC,SAAO,MAAM,IAAI;AACnB;AAKO,SAAS,YAAkB;AAChC,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,CAAC;AACjB,WAAO,UAAU,CAAC;AAAA,EACpB;AACF;AAKO,SAAS,SAAS,GAAW,GAAkB;AACpD,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,GAAG,CAAC;AAAA,EACtB;AACF;AAKO,SAAS,kBAAwB;AACtC,MAAI,OAAO,OAAO;AAChB,WAAO,gBAAgB;AAAA,EACzB;AACF;AAKO,SAAS,QAAiB;AAC/B,SAAO,OAAO,SAAS;AACzB;AAKO,SAAS,aAAqB;AACnC,SAAO,OAAO,WAAW;AAC3B;AAKO,SAAS,UAAkB;AAChC,SAAO,OAAO,QAAQ;AACxB;AAKO,SAAS,aAAmB;AACjC,MAAI,OAAO,SAAS,kBAAkB,6BAAa;AACjD,WAAO,MAAM,WAAa;AAAA,EAC5B;AACF;AAKO,SAAS,aAAmB;AACjC,MAAI,OAAO,SAAS,kBAAkB,6BAAa;AACjD,WAAO,MAAM,WAAa;AAAA,EAC5B;AACF;AAKO,SAAS,qBAA2B;AACzC,UAAQ,GAAG,QAAQ,UAAU;AAC7B,UAAQ,GAAG,UAAU,MAAM;AACzB,eAAW;AAEX,YAAQ,KAAK,GAAG;AAAA,EAClB,CAAC;AACD,UAAQ,GAAG,WAAW,MAAM;AAC1B,eAAW;AAEX,YAAQ,KAAK,GAAG;AAAA,EAClB,CAAC;AACH;",
+  "sourcesContent": ["/**\n * @fileoverview Standard output stream utilities.\n * Provides utilities for writing to stdout with formatting and control.\n */\n\nimport { WriteStream } from 'node:tty'\n\n// Get the actual stdout stream\nconst stdout: NodeJS.WriteStream = process.stdout\n\n/**\n * Write a line to stdout with trailing newline.\n *\n * @param text - Text to write\n * @default text ''\n *\n * @example\n * ```ts\n * writeLine('Hello, world!')\n * writeLine() // Write empty line\n * ```\n */\nexport function writeLine(text: string = ''): void {\n  stdout.write(`${text}\\n`)\n}\n\n/**\n * Write text to stdout without adding a newline.\n *\n * @param text - Text to write\n *\n * @example\n * ```ts\n * write('Loading...')\n * // Later: clear and update\n * ```\n */\nexport function write(text: string): void {\n  stdout.write(text)\n}\n\n/**\n * Clear the current line on stdout.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * write('Processing...')\n * clearLine()\n * write('Done!')\n * ```\n */\nexport function clearLine(): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(0)\n    stdout.clearLine(0)\n  }\n}\n\n/**\n * Move cursor to specific position on stdout.\n * Only works in TTY environments.\n *\n * @param x - Column position (0-based)\n * @param y - Row position (0-based, optional)\n *\n * @example\n * ```ts\n * cursorTo(0) // Move to start of line\n * cursorTo(10, 5) // Move to column 10, row 5\n * ```\n */\nexport function cursorTo(x: number, y?: number | undefined): void {\n  if (stdout.isTTY) {\n    stdout.cursorTo(x, y)\n  }\n}\n\n/**\n * Clear screen from cursor position down to bottom.\n * Only works in TTY environments.\n *\n * @example\n * ```ts\n * cursorTo(0, 5)\n * clearScreenDown() // Clear from row 5 to bottom\n * ```\n */\nexport function clearScreenDown(): void {\n  if (stdout.isTTY) {\n    stdout.clearScreenDown()\n  }\n}\n\n/**\n * Check if stdout is connected to a TTY (terminal).\n *\n * @returns `true` if stdout is a TTY, `false` if piped/redirected\n *\n * @example\n * ```ts\n * if (isTTY()) {\n *   // Show interactive UI\n * } else {\n *   // Use simple text output\n * }\n * ```\n */\nexport function isTTY(): boolean {\n  return stdout.isTTY || false\n}\n\n/**\n * Get the number of columns (width) in the terminal.\n *\n * @returns Terminal width in characters\n * @default 80\n *\n * @example\n * ```ts\n * const width = getColumns()\n * console.log(`Terminal is ${width} characters wide`)\n * ```\n */\nexport function getColumns(): number {\n  return stdout.columns || 80\n}\n\n/**\n * Get the number of rows (height) in the terminal.\n *\n * @returns Terminal height in lines\n * @default 24\n *\n * @example\n * ```ts\n * const height = getRows()\n * console.log(`Terminal is ${height} lines tall`)\n * ```\n */\nexport function getRows(): number {\n  return stdout.rows || 24\n}\n\n/**\n * Hide the cursor on stdout.\n * Useful for cleaner output during animations.\n *\n * @example\n * ```ts\n * hideCursor()\n * // Show animation\n * showCursor()\n * ```\n */\nexport function hideCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25l')\n  }\n}\n\n/**\n * Show the cursor on stdout.\n * Should be called after `hideCursor()`.\n *\n * @example\n * ```ts\n * hideCursor()\n * // Show animation\n * showCursor()\n * ```\n */\nexport function showCursor(): void {\n  if (stdout.isTTY && stdout instanceof WriteStream) {\n    stdout.write('\\u001B[?25h')\n  }\n}\n\n/**\n * Register handlers to ensure cursor is shown on process exit.\n * Prevents hidden cursor after abnormal termination.\n * Handles SIGINT (Ctrl+C) and SIGTERM signals.\n *\n * @example\n * ```ts\n * ensureCursorOnExit()\n * hideCursor()\n * // Even if process crashes, cursor will be restored\n * ```\n */\nexport function ensureCursorOnExit(): void {\n  process.on('exit', showCursor)\n  process.on('SIGINT', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(130)\n  })\n  process.on('SIGTERM', () => {\n    showCursor()\n    // eslint-disable-next-line n/no-process-exit\n    process.exit(143)\n  })\n}\n\n// Export the raw stream for advanced usage\nexport { stdout }\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAKA,sBAA4B;AAG5B,MAAM,SAA6B,QAAQ;AAcpC,SAAS,UAAU,OAAe,IAAU;AACjD,SAAO,MAAM,GAAG,IAAI;AAAA,CAAI;AAC1B;AAaO,SAAS,MAAM,MAAoB;AACxC,SAAO,MAAM,IAAI;AACnB;AAaO,SAAS,YAAkB;AAChC,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,CAAC;AACjB,WAAO,UAAU,CAAC;AAAA,EACpB;AACF;AAeO,SAAS,SAAS,GAAW,GAA8B;AAChE,MAAI,OAAO,OAAO;AAChB,WAAO,SAAS,GAAG,CAAC;AAAA,EACtB;AACF;AAYO,SAAS,kBAAwB;AACtC,MAAI,OAAO,OAAO;AAChB,WAAO,gBAAgB;AAAA,EACzB;AACF;AAgBO,SAAS,QAAiB;AAC/B,SAAO,OAAO,SAAS;AACzB;AAcO,SAAS,aAAqB;AACnC,SAAO,OAAO,WAAW;AAC3B;AAcO,SAAS,UAAkB;AAChC,SAAO,OAAO,QAAQ;AACxB;AAaO,SAAS,aAAmB;AACjC,MAAI,OAAO,SAAS,kBAAkB,6BAAa;AACjD,WAAO,MAAM,WAAa;AAAA,EAC5B;AACF;AAaO,SAAS,aAAmB;AACjC,MAAI,OAAO,SAAS,kBAAkB,6BAAa;AACjD,WAAO,MAAM,WAAa;AAAA,EAC5B;AACF;AAcO,SAAS,qBAA2B;AACzC,UAAQ,GAAG,QAAQ,UAAU;AAC7B,UAAQ,GAAG,UAAU,MAAM;AACzB,eAAW;AAEX,YAAQ,KAAK,GAAG;AAAA,EAClB,CAAC;AACD,UAAQ,GAAG,WAAW,MAAM;AAC1B,eAAW;AAEX,YAAQ,KAAK,GAAG;AAAA,EAClB,CAAC;AACH;",
   "names": []
 }

package/dist/strings.d.ts

@@ -23,117 +23,446 @@ export type EmptyString = string & {
 // See: https://github.com/SocketDev/socket-packageurl-js/issues/3
 export declare const fromCharCode: (...codes: number[]) => string;
 export interface ApplyLinePrefixOptions {
-    prefix?: string;
+    /**
+     * The prefix to add to each line.
+     * @default ''
+     */
+    prefix?: string | undefined;
 }
 /**
  * Apply a prefix to each line of a string.
+ *
+ * Prepends the specified prefix to the beginning of each line in the input string.
+ * If the string contains newlines, the prefix is added after each newline as well.
+ * When no prefix is provided or prefix is empty, returns the original string unchanged.
+ *
+ * @param str - The string to add prefixes to
+ * @param options - Configuration options
+ * @returns The string with prefix applied to each line
+ *
+ * @example
+ * ```ts
+ * applyLinePrefix('hello\nworld', { prefix: '> ' })
+ * // Returns: '> hello\n> world'
+ *
+ * applyLinePrefix('single line', { prefix: '  ' })
+ * // Returns: '  single line'
+ *
+ * applyLinePrefix('no prefix')
+ * // Returns: 'no prefix'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function applyLinePrefix(str: string, options?: ApplyLinePrefixOptions | undefined): string;
 /**
  * Convert a camelCase string to kebab-case.
+ *
+ * Transforms camelCase strings by converting uppercase letters to lowercase
+ * and inserting hyphens before uppercase sequences. Handles consecutive
+ * uppercase letters (like "XMLHttpRequest") by treating them as a single word.
+ * Returns empty string for empty input.
+ *
+ * Note: This function only handles camelCase. For mixed formats including
+ * snake_case, use `toKebabCase()` instead.
+ *
+ * @param str - The camelCase string to convert
+ * @returns The kebab-case string
+ *
+ * @example
+ * ```ts
+ * camelToKebab('helloWorld')
+ * // Returns: 'hello-world'
+ *
+ * camelToKebab('XMLHttpRequest')
+ * // Returns: 'xmlhttprequest'
+ *
+ * camelToKebab('iOS')
+ * // Returns: 'ios'
+ *
+ * camelToKebab('')
+ * // Returns: ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function camelToKebab(str: string): string;
 export interface IndentStringOptions {
-    count?: number;
+    /**
+     * Number of spaces to indent each line.
+     * @default 1
+     */
+    count?: number | undefined;
 }
 /**
  * Indent each line of a string with spaces.
+ *
+ * Adds the specified number of spaces to the beginning of each non-empty line
+ * in the input string. Empty lines (containing only whitespace) are not indented.
+ * Uses a regular expression to efficiently handle multi-line strings.
+ *
+ * @param str - The string to indent
+ * @param options - Configuration options
+ * @returns The indented string
+ *
+ * @example
+ * ```ts
+ * indentString('hello\nworld', { count: 2 })
+ * // Returns: '  hello\n  world'
+ *
+ * indentString('line1\n\nline3', { count: 4 })
+ * // Returns: '    line1\n\n    line3'
+ *
+ * indentString('single line')
+ * // Returns: ' single line' (default: 1 space)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function indentString(str: string, options?: IndentStringOptions | undefined): string;
 /**
  * Check if a value is a blank string (empty or only whitespace).
+ *
+ * A blank string is defined as a string that is either:
+ * - Completely empty (length 0)
+ * - Contains only whitespace characters (spaces, tabs, newlines, etc.)
+ *
+ * This is useful for validation when you need to ensure user input
+ * contains actual content, not just whitespace.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a blank string, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isBlankString('')
+ * // Returns: true
+ *
+ * isBlankString('   ')
+ * // Returns: true
+ *
+ * isBlankString('\n\t  ')
+ * // Returns: true
+ *
+ * isBlankString('hello')
+ * // Returns: false
+ *
+ * isBlankString(null)
+ * // Returns: false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isBlankString(value: unknown): value is BlankString;
 /**
  * Check if a value is a non-empty string.
+ *
+ * Returns `true` only if the value is a string with at least one character.
+ * This includes strings containing only whitespace (use `isBlankString()` if
+ * you want to exclude those). Type guard ensures TypeScript knows the value
+ * is a string after this check.
+ *
+ * @param value - The value to check
+ * @returns `true` if the value is a non-empty string, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isNonEmptyString('hello')
+ * // Returns: true
+ *
+ * isNonEmptyString('   ')
+ * // Returns: true (contains whitespace)
+ *
+ * isNonEmptyString('')
+ * // Returns: false
+ *
+ * isNonEmptyString(null)
+ * // Returns: false
+ *
+ * isNonEmptyString(123)
+ * // Returns: false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function isNonEmptyString(value: unknown): value is Exclude<string, EmptyString>;
 export interface SearchOptions {
-    fromIndex?: number;
+    /**
+     * The position in the string to begin searching from.
+     * Negative values count back from the end of the string.
+     * @default 0
+     */
+    fromIndex?: number | undefined;
 }
 /**
  * Search for a regular expression in a string starting from an index.
+ *
+ * Similar to `String.prototype.search()` but allows specifying a starting
+ * position. Returns the index of the first match at or after `fromIndex`,
+ * or -1 if no match is found. Negative `fromIndex` values count back from
+ * the end of the string.
+ *
+ * This is more efficient than using `str.slice(fromIndex).search()` when
+ * you need the absolute position in the original string, as it handles
+ * the offset calculation for you.
+ *
+ * @param str - The string to search in
+ * @param regexp - The regular expression to search for
+ * @param options - Configuration options
+ * @returns The index of the first match, or -1 if not found
+ *
+ * @example
+ * ```ts
+ * search('hello world hello', /hello/, { fromIndex: 0 })
+ * // Returns: 0 (first 'hello')
+ *
+ * search('hello world hello', /hello/, { fromIndex: 6 })
+ * // Returns: 12 (second 'hello')
+ *
+ * search('hello world', /goodbye/, { fromIndex: 0 })
+ * // Returns: -1 (not found)
+ *
+ * search('hello world', /hello/, { fromIndex: -5 })
+ * // Returns: -1 (starts searching from 'world', no match)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function search(str: string, regexp: RegExp, options?: SearchOptions | undefined): number;
 /**
  * Strip the Byte Order Mark (BOM) from the beginning of a string.
+ *
+ * The BOM (U+FEFF) is a Unicode character that can appear at the start of
+ * a text file to indicate byte order and encoding. In UTF-16 (JavaScript's
+ * internal string representation), it appears as 0xFEFF. This function
+ * removes it if present, leaving the rest of the string unchanged.
+ *
+ * Most text processing doesn't need to handle the BOM explicitly, but it
+ * can cause issues when parsing JSON, CSV, or other structured data formats
+ * that don't expect a leading invisible character.
+ *
+ * @param str - The string to strip BOM from
+ * @returns The string without BOM
+ *
+ * @example
+ * ```ts
+ * stripBom('\uFEFFhello world')
+ * // Returns: 'hello world'
+ *
+ * stripBom('hello world')
+ * // Returns: 'hello world' (no BOM to strip)
+ *
+ * stripBom('')
+ * // Returns: ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function stripBom(str: string): string;
 /**
  * Get the visual width of a string in terminal columns.
- * Strips ANSI escape codes and accounts for wide characters.
  *
- * Based on string-width:
+ * Calculates how many columns a string will occupy when displayed in a terminal,
+ * accounting for:
+ * - ANSI escape codes (stripped before calculation)
+ * - Wide characters (CJK ideographs, fullwidth forms) that take 2 columns
+ * - Emoji (including complex sequences) that take 2 columns
+ * - Combining marks and zero-width characters (take 0 columns)
+ * - East Asian Width properties (Fullwidth, Wide, Halfwidth, Narrow, etc.)
+ *
+ * Based on string-width by Sindre Sorhus:
  * https://socket.dev/npm/package/string-width/overview/7.2.0
  * MIT License
  * Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
  *
  * Terminal emulators display characters in a grid of cells (columns).
  * Most ASCII characters take 1 column, but some characters (especially
- * emoji and CJK characters) take 2 columns.
- *
- * This function calculates how many columns a string will occupy when
- * displayed in a terminal, which is crucial for:
- * - Aligning text properly
+ * emoji and CJK characters) take 2 columns. This function calculates
+ * the actual visual width, which is crucial for:
+ * - Aligning text properly in tables or columns
  * - Preventing text from jumping when characters change
- * - Calculating padding/spacing
+ * - Calculating padding/spacing for spinners and progress bars
+ * - Wrapping text at the correct column width
  *
- * Logic:
- * - Segment graphemes to match how terminals render clusters.
- * - Width rules:
- *   1. Skip non-printing clusters (Default_Ignorable, Control, pure Mark, lone Surrogates).
- *   2. RGI emoji clusters (\p{RGI_Emoji}) are double-width.
- *   3. Otherwise use East Asian Width of the cluster's first visible code point.
- *   4. Add widths for trailing Halfwidth/Fullwidth Forms within the same cluster.
+ * Algorithm Overview:
+ * 1. Strip ANSI escape codes (invisible in terminal)
+ * 2. Segment into grapheme clusters (user-perceived characters)
+ * 3. For each cluster:
+ *    - Skip zero-width/non-printing clusters (width = 0)
+ *    - RGI emoji clusters are double-width (width = 2)
+ *    - Otherwise use East Asian Width of first visible code point
+ *    - Add width for trailing Halfwidth/Fullwidth Forms
  *
- * East Asian Width categories (Unicode Standard Annex #11):
+ * East Asian Width Categories (Unicode Standard Annex #11):
  * - F (Fullwidth): 2 columns - e.g., fullwidth Latin letters (Ａ, Ｂ)
  * - W (Wide): 2 columns - e.g., CJK ideographs (漢字), emoji (⚡, 😀)
  * - H (Halfwidth): 1 column - e.g., halfwidth Katakana (ｱ, ｲ)
  * - Na (Narrow): 1 column - e.g., ASCII (a-z, 0-9)
- * - A (Ambiguous): Context-dependent, we treat as 1 column
+ * - A (Ambiguous): Context-dependent, treated as 1 column by default
  * - N (Neutral): 1 column - e.g., most symbols (✦, ✧, ⋆)
  *
- * Why this matters for Socket spinners:
+ * Why This Matters for Socket:
  * - Lightning bolt (⚡) takes 2 columns
  * - Stars (✦, ✧, ⋆) take 1 column
- * - Without compensation, text jumps when frames change
- * - We use this to calculate padding for consistent alignment
+ * - Without proper width calculation, spinner text jumps between frames
+ * - This function enables consistent alignment by calculating padding
+ *
+ * @param text - The string to measure
+ * @returns The visual width in terminal columns
  *
  * @example
- * stringWidth('hello') // => 5 (5 ASCII chars = 5 columns)
- * stringWidth('⚡') // => 2 (lightning bolt is wide)
- * stringWidth('✦') // => 1 (star is narrow)
- * stringWidth('\x1b[31mred\x1b[0m') // => 3 (ANSI codes stripped, 'red' = 3)
+ * ```ts
+ * stringWidth('hello')
+ * // Returns: 5 (5 ASCII chars = 5 columns)
+ *
+ * stringWidth('⚡')
+ * // Returns: 2 (lightning bolt is wide)
+ *
+ * stringWidth('✦')
+ * // Returns: 1 (star is narrow)
+ *
+ * stringWidth('漢字')
+ * // Returns: 4 (2 CJK characters × 2 columns each)
+ *
+ * stringWidth('\x1b[31mred\x1b[0m')
+ * // Returns: 3 (ANSI codes stripped, 'red' = 3)
+ *
+ * stringWidth('👍🏽')
+ * // Returns: 2 (emoji with skin tone = 1 grapheme cluster = 2 columns)
  *
- * @throws {TypeError} When input is not a string.
+ * stringWidth('é')
+ * // Returns: 1 (combining accent doesn't add width)
+ *
+ * stringWidth('')
+ * // Returns: 0
+ * ```
+ *
+ * @throws {TypeError} When input is not a string
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function stringWidth(text: string): number;
 /**
  * Convert a string to kebab-case (handles camelCase and snake_case).
+ *
+ * Transforms strings from camelCase or snake_case to kebab-case by:
+ * - Converting uppercase letters to lowercase
+ * - Inserting hyphens before uppercase letters (for camelCase)
+ * - Replacing underscores with hyphens (for snake_case)
+ *
+ * This is more comprehensive than `camelToKebab()` as it handles mixed
+ * formats including snake_case. Returns empty string for empty input.
+ *
+ * @param str - The string to convert
+ * @returns The kebab-case string
+ *
+ * @example
+ * ```ts
+ * toKebabCase('helloWorld')
+ * // Returns: 'hello-world'
+ *
+ * toKebabCase('hello_world')
+ * // Returns: 'hello-world'
+ *
+ * toKebabCase('XMLHttpRequest')
+ * // Returns: 'xmlhttp-request'
+ *
+ * toKebabCase('iOS_Version')
+ * // Returns: 'io-s-version'
+ *
+ * toKebabCase('')
+ * // Returns: ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function toKebabCase(str: string): string;
 /**
  * Trim newlines from the beginning and end of a string.
+ *
+ * Removes all leading and trailing newline characters (both `\n` and `\r`)
+ * from a string, while preserving any newlines in the middle. This is similar
+ * to `String.prototype.trim()` but specifically targets newlines instead of
+ * all whitespace.
+ *
+ * Optimized for performance by checking the first and last characters before
+ * doing any string manipulation. Returns the original string unchanged if no
+ * newlines are found at the edges.
+ *
+ * @param str - The string to trim
+ * @returns The string with leading and trailing newlines removed
+ *
+ * @example
+ * ```ts
+ * trimNewlines('\n\nhello\n\n')
+ * // Returns: 'hello'
+ *
+ * trimNewlines('\r\nworld\r\n')
+ * // Returns: 'world'
+ *
+ * trimNewlines('hello\nworld')
+ * // Returns: 'hello\nworld' (middle newline preserved)
+ *
+ * trimNewlines('  hello  ')
+ * // Returns: '  hello  ' (spaces not trimmed, only newlines)
+ *
+ * trimNewlines('hello')
+ * // Returns: 'hello'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function trimNewlines(str: string): string;
 /**
  * Repeat a string n times.
+ *
+ * Creates a new string by repeating the input string the specified number of times.
+ * Returns an empty string if count is zero or negative. This is a simple wrapper
+ * around `String.prototype.repeat()` with guard for non-positive counts.
+ *
+ * @param str - The string to repeat
+ * @param count - The number of times to repeat the string
+ * @returns The repeated string, or empty string if count <= 0
+ *
+ * @example
+ * ```ts
+ * repeatString('hello', 3)
+ * // Returns: 'hellohellohello'
+ *
+ * repeatString('x', 5)
+ * // Returns: 'xxxxx'
+ *
+ * repeatString('hello', 0)
+ * // Returns: ''
+ *
+ * repeatString('hello', -1)
+ * // Returns: ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function repeatString(str: string, count: number): string;
 /**
  * Center text within a given width.
+ *
+ * Adds spaces before and after the text to center it within the specified width.
+ * Distributes padding evenly on both sides. When the padding is odd, the extra
+ * space is added to the right side. Strips ANSI codes before calculating text
+ * length to ensure accurate centering of colored text.
+ *
+ * If the text is already wider than or equal to the target width, returns the
+ * original text unchanged (no truncation occurs).
+ *
+ * @param text - The text to center (may include ANSI codes)
+ * @param width - The target width in columns
+ * @returns The centered text with padding
+ *
+ * @example
+ * ```ts
+ * centerText('hello', 11)
+ * // Returns: '   hello   ' (3 spaces on each side)
+ *
+ * centerText('hi', 10)
+ * // Returns: '    hi    ' (4 spaces on each side)
+ *
+ * centerText('odd', 8)
+ * // Returns: '  odd   ' (2 left, 3 right)
+ *
+ * centerText('\x1b[31mred\x1b[0m', 7)
+ * // Returns: '  \x1b[31mred\x1b[0m  ' (ANSI codes preserved, 'red' centered)
+ *
+ * centerText('too long text', 5)
+ * // Returns: 'too long text' (no truncation, returned as-is)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export declare function centerText(text: string, width: number): string;