@socketsecurity/lib 5.28.0 → 6.0.1

package/dist/streams/transform.js

@@ -0,0 +1,48 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var transform_exports = {};
+__export(transform_exports, {
+  transform: () => transform
+});
+module.exports = __toCommonJS(transform_exports);
+var import_streaming_iterables = require("../external/streaming-iterables");
+var import_options = require("../promises/options");
+var import_retry = require("../promises/retry");
+// @__NO_SIDE_EFFECTS__
+function transform(iterable, func, options) {
+  const opts = (0, import_options.normalizeIterationOptions)(options);
+  const result = (0, import_streaming_iterables.transform)(
+    opts.concurrency,
+    async (item) => {
+      const result2 = await (0, import_retry.pRetry)((...args) => func(args[0]), {
+        ...opts.retries,
+        args: [item]
+      });
+      return result2;
+    },
+    iterable
+  );
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  transform
+});

package/dist/strings/format.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @file Line formatting helpers: `applyLinePrefix`, `centerText`,
+ *   `indentString`, `repeatString`. Plus the `fromCharCode` re-export so
+ *   callers don't have to reach into `primordials/string` for the most common
+ *   use case.
+ */
+import type { ApplyLinePrefixOptions, IndentStringOptions } from './types';
+export declare const fromCharCode: (...codes: number[]) => string;
+/**
+ * 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.
+ *
+ * @example
+ *   ;```ts
+ *   applyLinePrefix('hello\nworld', { prefix: '> ' })
+ *   // Returns: '> hello\n> world'
+ *
+ *   applyLinePrefix('single line', { prefix: '  ' })
+ *   // Returns: '  single line'
+ *
+ *   applyLinePrefix('no prefix')
+ *   // Returns: 'no prefix'
+ *   ```
+ *
+ * @param str - The string to add prefixes to.
+ * @param options - Configuration options.
+ *
+ * @returns The string with prefix applied to each line
+ */
+export declare function applyLinePrefix(str: string, options?: ApplyLinePrefixOptions | undefined): 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).
+ *
+ * @example
+ *   ;```ts
+ *   centerText('hello', 11)
+ *   // Returns: '   hello   '
+ *
+ *   centerText('hi', 10)
+ *   // Returns: '    hi    '
+ *
+ *   centerText('odd', 8)
+ *   // Returns: '  odd   ' (2 left, 3 right)
+ *
+ *   centerText('\x1b[31mred\x1b[0m', 7)
+ *   // Returns: '  \x1b[31mred\x1b[0m  '
+ *
+ *   centerText('too long text', 5)
+ *   // Returns: 'too long text' (no truncation)
+ *   ```
+ *
+ * @param text - The text to center (may include ANSI codes)
+ * @param width - The target width in columns.
+ *
+ * @returns The centered text with padding
+ */
+export declare function centerText(text: string, width: number): string;
+/**
+ * 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.
+ *
+ * @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)
+ *   ```
+ *
+ * @param str - The string to indent.
+ * @param options - Configuration options.
+ *
+ * @returns The indented string
+ */
+export declare function indentString(str: string, options?: IndentStringOptions | undefined): string;
+/**
+ * Repeat a string a specified number of times.
+ *
+ * Creates a new string by repeating the input string `count` times. Returns an
+ * empty string if count is 0 or negative.
+ *
+ * @example
+ *   ;```ts
+ *   repeatString('hello', 3) // 'hellohellohello'
+ *   repeatString('x', 5) // 'xxxxx'
+ *   repeatString('hello', 0) // ''
+ *   repeatString('hello', -1) // ''
+ *   ```
+ *
+ * @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
+ */
+export declare function repeatString(str: string, count: number): string;

package/dist/strings/format.js

@@ -0,0 +1,73 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var format_exports = {};
+__export(format_exports, {
+  applyLinePrefix: () => applyLinePrefix,
+  centerText: () => centerText,
+  fromCharCode: () => fromCharCode,
+  indentString: () => indentString,
+  repeatString: () => repeatString
+});
+module.exports = __toCommonJS(format_exports);
+var import_strip = require("../ansi/strip");
+var import_math = require("../primordials/math");
+var import_string = require("../primordials/string");
+const fromCharCode = String.fromCharCode;
+// @__NO_SIDE_EFFECTS__
+function applyLinePrefix(str, options) {
+  const { prefix = "" } = {
+    __proto__: null,
+    ...options
+  };
+  return prefix.length ? `${prefix}${(0, import_string.StringPrototypeIncludes)(str, "\n") ? str.replace(/\n/g, `
+${prefix}`) : str}` : str;
+}
+// @__NO_SIDE_EFFECTS__
+function centerText(text, width) {
+  const textLength = (0, import_strip.stripAnsi)(text).length;
+  if (textLength >= width) {
+    return text;
+  }
+  const padding = width - textLength;
+  const leftPad = (0, import_math.MathFloor)(padding / 2);
+  const rightPad = padding - leftPad;
+  return " ".repeat(leftPad) + text + " ".repeat(rightPad);
+}
+// @__NO_SIDE_EFFECTS__
+function indentString(str, options) {
+  const { count = 1 } = { __proto__: null, ...options };
+  return str.replace(/^(?!\s*$)/gm, " ".repeat(count));
+}
+// @__NO_SIDE_EFFECTS__
+function repeatString(str, count) {
+  if (count <= 0) {
+    return "";
+  }
+  return (0, import_string.StringPrototypeRepeat)(str, count);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyLinePrefix,
+  centerText,
+  fromCharCode,
+  indentString,
+  repeatString
+});

package/dist/strings/predicates.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file String predicates: `isBlankString` and `isNonEmptyString`. Both are
+ *   TypeScript type guards so callers can narrow `unknown` → `string` (or
+ *   `BlankString` / non-empty string) without an extra cast.
+ */
+import type { BlankString, EmptyString } from './types';
+/**
+ * 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.
+ *
+ * @example
+ *   ;```ts
+ *   isBlankString('') // true
+ *   isBlankString('   ') // true
+ *   isBlankString('\n\t  ') // true
+ *   isBlankString('hello') // false
+ *   isBlankString(null) // false
+ *   ```
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is a blank string, `false` otherwise
+ */
+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.
+ *
+ * @example
+ *   ;```ts
+ *   isNonEmptyString('hello') // true
+ *   isNonEmptyString('   ') // true (contains whitespace)
+ *   isNonEmptyString('') // false
+ *   isNonEmptyString(null) // false
+ *   isNonEmptyString(123) // false
+ *   ```
+ *
+ * @param value - The value to check.
+ *
+ * @returns `true` if the value is a non-empty string, `false` otherwise
+ */
+export declare function isNonEmptyString(value: unknown): value is Exclude<string, EmptyString>;

package/dist/strings/predicates.js

@@ -0,0 +1,39 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var predicates_exports = {};
+__export(predicates_exports, {
+  isBlankString: () => isBlankString,
+  isNonEmptyString: () => isNonEmptyString
+});
+module.exports = __toCommonJS(predicates_exports);
+// @__NO_SIDE_EFFECTS__
+function isBlankString(value) {
+  return typeof value === "string" && (!value.length || /^\s+$/.test(value));
+}
+// @__NO_SIDE_EFFECTS__
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isBlankString,
+  isNonEmptyString
+});

package/dist/strings/search.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @file `search` — like `String.prototype.search` but with a configurable
+ *   starting index. The native `RegExp.exec` + `lastIndex` dance handles this,
+ *   but with side-effect risk on shared regexes. This wrapper offers a clean,
+ *   side-effect-free version.
+ */
+import type { SearchOptions } from './types';
+/**
+ * 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.
+ *
+ * @example
+ *   ;```ts
+ *   search('hello world hello', /hello/, { fromIndex: 0 }) // 0
+ *   search('hello world hello', /hello/, { fromIndex: 6 }) // 12
+ *   search('hello world', /goodbye/, { fromIndex: 0 }) // -1
+ *   search('hello world', /hello/, { fromIndex: -5 }) // -1
+ *   ```
+ *
+ * @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
+ */
+export declare function search(str: string, regexp: RegExp, options?: SearchOptions | undefined): number;

package/dist/strings/search.js

@@ -0,0 +1,45 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var search_exports = {};
+__export(search_exports, {
+  search: () => search
+});
+module.exports = __toCommonJS(search_exports);
+var import_math = require("../primordials/math");
+var import_string = require("../primordials/string");
+// @__NO_SIDE_EFFECTS__
+function search(str, regexp, options) {
+  const { fromIndex = 0 } = { __proto__: null, ...options };
+  const { length } = str;
+  if (fromIndex >= length) {
+    return -1;
+  }
+  if (fromIndex === 0) {
+    return (0, import_string.StringPrototypeSearch)(str, regexp);
+  }
+  const offset = fromIndex < 0 ? (0, import_math.MathMax)(length + fromIndex, 0) : fromIndex;
+  const result = (0, import_string.StringPrototypeSlice)(str, offset).search(regexp);
+  return result === -1 ? -1 : result + offset;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  search
+});

package/dist/strings/transform.d.ts

@@ -0,0 +1,80 @@
+/**
+ * @file String transformations: `stripBom`, `toKebabCase`, `trimNewlines`. All
+ *   three are pure functions with no side effects.
+ */
+/**
+ * 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.
+ *
+ * @example
+ *   ;```ts
+ *   stripBom('hello world') // 'hello world'
+ *   stripBom('hello world') // 'hello world'
+ *   stripBom('') // ''
+ *   ```
+ *
+ * @param str - The string to strip BOM from.
+ *
+ * @returns The string without BOM
+ */
+export declare function stripBom(str: string): string;
+/**
+ * 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)
+ *
+ * Handles mixed formats (camelCase, snake_case, acronyms) in one pass. Returns
+ * empty string for empty input.
+ *
+ * @example
+ *   ;```ts
+ *   toKebabCase('helloWorld') // 'hello-world'
+ *   toKebabCase('hello_world') // 'hello-world'
+ *   toKebabCase('XMLHttpRequest') // 'xmlhttp-request'
+ *   toKebabCase('iOS_Version') // 'i-os-version'
+ *   toKebabCase('') // ''
+ *   ```
+ *
+ * @param str - The string to convert.
+ *
+ * @returns The kebab-case string
+ */
+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.
+ *
+ * @example
+ *   ;```ts
+ *   trimNewlines('\n\nhello\n\n') // 'hello'
+ *   trimNewlines('\r\nworld\r\n') // 'world'
+ *   trimNewlines('hello\nworld') // 'hello\nworld' (middle preserved)
+ *   trimNewlines('  hello  ') // '  hello  ' (spaces not trimmed)
+ *   trimNewlines('hello') // 'hello'
+ *   ```
+ *
+ * @param str - The string to trim.
+ *
+ * @returns The string with leading and trailing newlines removed
+ */
+export declare function trimNewlines(str: string): string;

package/dist/strings/transform.js

@@ -0,0 +1,79 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var transform_exports = {};
+__export(transform_exports, {
+  stripBom: () => stripBom,
+  toKebabCase: () => toKebabCase,
+  trimNewlines: () => trimNewlines
+});
+module.exports = __toCommonJS(transform_exports);
+var import_string = require("../primordials/string");
+// @__NO_SIDE_EFFECTS__
+function stripBom(str) {
+  return str.length > 0 && (0, import_string.StringPrototypeCharCodeAt)(str, 0) === 65279 ? (0, import_string.StringPrototypeSlice)(str, 1) : str;
+}
+// @__NO_SIDE_EFFECTS__
+function toKebabCase(str) {
+  if (!str.length) {
+    return str;
+  }
+  return (0, import_string.StringPrototypeReplace)(str, /([a-z]+[0-9]*)([A-Z])/g, "$1-$2").replace(/_/g, "-").toLowerCase();
+}
+// @__NO_SIDE_EFFECTS__
+function trimNewlines(str) {
+  const { length } = str;
+  if (length === 0) {
+    return str;
+  }
+  const first = (0, import_string.StringPrototypeCharCodeAt)(str, 0);
+  const noFirstNewline = first !== 13 && first !== 10;
+  if (length === 1) {
+    return noFirstNewline ? str : "";
+  }
+  const last = (0, import_string.StringPrototypeCharCodeAt)(str, length - 1);
+  const noLastNewline = last !== 13 && last !== 10;
+  if (noFirstNewline && noLastNewline) {
+    return str;
+  }
+  let start = 0;
+  let end = length;
+  while (start < end) {
+    const code = (0, import_string.StringPrototypeCharCodeAt)(str, start);
+    if (code !== 13 && code !== 10) {
+      break;
+    }
+    start += 1;
+  }
+  while (end > start) {
+    const code = (0, import_string.StringPrototypeCharCodeAt)(str, end - 1);
+    if (code !== 13 && code !== 10) {
+      break;
+    }
+    end -= 1;
+  }
+  return start === 0 && end === length ? str : (0, import_string.StringPrototypeSlice)(str, start, end);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  stripBom,
+  toKebabCase,
+  trimNewlines
+});

package/dist/strings/types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * @file Public type surface for `strings/*` modules — branded string types and
+ *   option interfaces. Pure types, no runtime side effects.
+ */
+declare const BlankStringBrand: unique symbol;
+export type BlankString = string & {
+    [BlankStringBrand]: true;
+};
+declare const EmptyStringBrand: unique symbol;
+export type EmptyString = string & {
+    [EmptyStringBrand]: true;
+};
+export interface ApplyLinePrefixOptions {
+    /**
+     * The prefix to add to each line.
+     *
+     * @default ''
+     */
+    prefix?: string | undefined;
+}
+export interface IndentStringOptions {
+    /**
+     * Number of spaces to indent each line.
+     *
+     * @default 1
+     */
+    count?: number | undefined;
+}
+export interface SearchOptions {
+    /**
+     * The position in the string to begin searching from. Negative values count
+     * back from the end of the string.
+     *
+     * @default 0
+     */
+    fromIndex?: number | undefined;
+}
+export {};

package/dist/strings/types.js

@@ -0,0 +1,18 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/strings/width.d.ts

@@ -0,0 +1,42 @@
+/**
+ * @file `stringWidth` — calculate visual terminal width. Based on string-width
+ *   by Sindre Sorhus
+ *   (https://socket.dev/npm/package/string-width/overview/7.2.0, MIT). Why this
+ *   lives in its own leaf:
+ *
+ *   - It carries a heavy module-level setup: `Intl.Segmenter` instance,
+ *     feature-detected regex patterns (with `'v'` flag fallback to `'u'`), and
+ *     a lazy `eastAsianWidth` accessor.
+ *   - The function body is ~150 lines of carefully-commented Unicode handling —
+ *     keeping it isolated makes it easy to review changes without touching the
+ *     rest of the strings surface. See the comments inside for the algorithm
+ *     details and Unicode Standard Annex #11 references.
+ */
+import type { eastAsianWidth as eastAsianWidthType } from '../external/get-east-asian-width';
+export declare function getEastAsianWidth(): typeof eastAsianWidthType;
+/**
+ * Get the visual width of a string in terminal columns.
+ *
+ * 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.)
+ *
+ * @example
+ *   ;```ts
+ *   stringWidth('hello') // 5
+ *   stringWidth('⚡') // 2 (lightning bolt is wide)
+ *   stringWidth('✦') // 1 (star is narrow)
+ *   stringWidth('漢字') // 4 (CJK × 2 cols each)
+ *   stringWidth('\x1b[31mred\x1b[0m') // 3 (ANSI stripped)
+ *   stringWidth('👍🏽') // 2 (emoji + skin tone = 1 cluster)
+ *   stringWidth('é') // 1 (combining accent = 0 width)
+ *   ```
+ *
+ * @param text - The string to measure.
+ *
+ * @returns The visual width in terminal columns
+ */
+export declare function stringWidth(text: string): number;