@visulima/string 3.0.0-alpha.11 → 3.0.0-alpha.13

package/dist/truncate.d.ts

@@ -1,10 +1,53 @@
 import { StringTruncatedWidthOptions } from "./get-string-truncated-width.js";
 type TruncateOptions = {
+  /**
+  * Text appended to the string when it is truncated
+  * @default '…'
+  */
   ellipsis?: string;
+  /**
+  * Width of the ellipsis string
+  * If not provided, it will be calculated using getStringTruncatedWidth
+  */
   ellipsisWidth?: number;
+  /**
+  * The position to truncate the string.
+  * @default 'end'
+  */
   position?: "end" | "middle" | "start";
+  /**
+  * Truncate the string from a whitespace if it is within 3 characters from the actual breaking point.
+  * @default false
+  */
   preferTruncationOnSpace?: boolean;
+  /**
+  * Width calculation options
+  */
   width?: Omit<StringTruncatedWidthOptions, "ellipsis" | "ellipsisWidth" | "limit">;
 };
+/**
+* Truncates a string to a specified width limit, handling Unicode characters, ANSI escape codes,
+* and adding an optional ellipsis.
+*
+* ANSI Sequence Handling:
+* - Valid ANSI sequences (e.g. '\u001b[31m') are preserved and handled as styling
+* - Incomplete sequences are preserved as-is
+* - Missing terminators are preserved as-is
+* @example
+* ```typescript
+* // Basic usage
+* truncate('Hello World', 5); // 'Hello…'
+*
+* // With valid ANSI styling
+* truncate('\u001b[31mRed\u001b[0m Text', 3); // '\u001b[31mRed\u001b[0m…'
+*
+* // With invalid ANSI sequence
+* truncate('\u001b[abcText', 4); // '\u001b[abcText'
+* ```
+* @param input The string to truncate
+* @param limit Maximum width of the returned string
+* @param options Configuration options for truncation
+* @returns The truncated string with ellipsis if applicable
+*/
 declare const truncate: (input: string, limit: number, options?: TruncateOptions) => string;
 export { TruncateOptions, truncate };

package/dist/truncate.js

@@ -1,112 +1 @@
-import { getStringTruncatedWidth } from './get-string-truncated-width.js';
-import { getStringWidth } from './get-string-width.js';
-import { slice } from './slice.js';
-
-const DEFAULT_ELLIPSIS = "…";
-const MAX_SPACE_SEARCH_DISTANCE = 3;
-const findNearestSpace = (value, startIndex, searchRight = false) => {
-  if (value.charAt(startIndex) === " ") {
-    return startIndex;
-  }
-  const direction = searchRight ? 1 : -1;
-  const limit = Math.min(MAX_SPACE_SEARCH_DISTANCE, searchRight ? value.length - startIndex : startIndex);
-  for (let offset = 1; offset <= limit; offset++) {
-    const index = startIndex + offset * direction;
-    if (value.charAt(index) === " ") {
-      return index;
-    }
-  }
-  return startIndex;
-};
-const widthToIndex = (input, targetWidth, widthOptions) => {
-  const result = getStringTruncatedWidth(input, {
-    ...widthOptions,
-    ellipsis: "",
-    ellipsisWidth: 0,
-    limit: targetWidth
-  });
-  return result.index;
-};
-const indexToWidth = (input, stringIndex, widthOptions) => getStringWidth(input.slice(0, stringIndex), widthOptions);
-const truncate = (input, limit, options = {}) => {
-  if (typeof input !== "string") {
-    throw new TypeError(`Expected \`input\` to be a string, got ${typeof input}`);
-  }
-  if (typeof limit !== "number") {
-    throw new TypeError(`Expected \`limit\` to be a number, got ${typeof limit}`);
-  }
-  if (input === "" || limit <= 0) {
-    return "";
-  }
-  const normalizedInput = input.normalize("NFC");
-  const { ellipsis = DEFAULT_ELLIPSIS, position = "end", preferTruncationOnSpace = false } = options;
-  let ellipsisWidth = options.ellipsisWidth ?? ellipsis === DEFAULT_ELLIPSIS ? 1 : void 0;
-  ellipsisWidth ??= getStringTruncatedWidth(ellipsis, {
-    ...options.width,
-    ellipsis: "",
-    ellipsisWidth: 0,
-    limit: Number.POSITIVE_INFINITY
-  }).width;
-  const { width } = getStringTruncatedWidth(normalizedInput, {
-    ...options.width,
-    ellipsis,
-    ellipsisWidth
-  });
-  if (width <= limit) {
-    return normalizedInput;
-  }
-  switch (position) {
-    case "end": {
-      if (preferTruncationOnSpace) {
-        const targetWidth = limit - ellipsisWidth;
-        const stringIndex = widthToIndex(normalizedInput, targetWidth, options.width);
-        const nearestSpace = findNearestSpace(normalizedInput, stringIndex);
-        const nearestSpaceWidth = indexToWidth(normalizedInput, nearestSpace, options.width);
-        return slice(normalizedInput, 0, nearestSpaceWidth, {
-          width: options.width
-        }) + ellipsis;
-      }
-      return slice(normalizedInput, 0, limit - ellipsisWidth, {
-        width: options.width
-      }) + ellipsis;
-    }
-    case "middle": {
-      const half = Math.floor(limit / 2);
-      const totalTextWidth = Math.max(0, limit - ellipsisWidth);
-      const leftWidth = Math.min(half, totalTextWidth);
-      const rightWidth = Math.max(0, totalTextWidth - leftWidth);
-      if (preferTruncationOnSpace) {
-        const firstBreakIndex = widthToIndex(normalizedInput, leftWidth, options.width);
-        const firstBreak = findNearestSpace(normalizedInput, firstBreakIndex);
-        const firstBreakWidth = indexToWidth(normalizedInput, firstBreak, options.width);
-        const secondBreakWidthTarget = width - rightWidth;
-        const secondBreakIndex = widthToIndex(normalizedInput, secondBreakWidthTarget, options.width);
-        const secondBreak = findNearestSpace(normalizedInput, secondBreakIndex, true);
-        const secondBreakWidthActual = indexToWidth(normalizedInput, secondBreak, options.width);
-        return slice(normalizedInput, 0, firstBreakWidth, { width: options.width }) + ellipsis + slice(normalizedInput, secondBreakWidthActual, width, { width: options.width }).trim();
-      }
-      return slice(normalizedInput, 0, leftWidth, {
-        width: options.width
-      }) + ellipsis + slice(normalizedInput, width - rightWidth, width, {
-        width: options.width
-      });
-    }
-    case "start": {
-      if (preferTruncationOnSpace) {
-        const targetWidth = width - limit + ellipsisWidth;
-        const stringIndex = widthToIndex(normalizedInput, targetWidth, options.width);
-        const nearestSpace = findNearestSpace(normalizedInput, stringIndex, true);
-        const nearestSpaceWidth = indexToWidth(normalizedInput, nearestSpace, options.width);
-        return ellipsis + slice(normalizedInput, nearestSpaceWidth, width, { width: options.width }).trim();
-      }
-      return ellipsis + slice(normalizedInput, width - limit + ellipsisWidth, width, {
-        width: options.width
-      });
-    }
-    default: {
-      throw new Error(`Invalid position: expected 'start', 'middle' or 'end', got '${position}'`);
-    }
-  }
-};
-
-export { truncate };
+var N=Object.defineProperty;var T=(r,i)=>N(r,"name",{value:i,configurable:!0});import{getStringTruncatedWidth as x}from"./get-string-truncated-width.js";import{getStringWidth as O}from"./get-string-width.js";import{slice as h}from"./slice.js";var A=Object.defineProperty,g=T((r,i)=>A(r,"name",{value:i,configurable:!0}),"f");const b="…",$=3,u=g((r,i,t=!1)=>{if(r.charAt(i)===" ")return i;const e=t?1:-1,d=Math.min($,t?r.length-i:i);for(let w=1;w<=d;w++){const l=i+w*e;if(r.charAt(l)===" ")return l}return i},"findNearestSpace"),f=g((r,i,t)=>x(r,{...t,ellipsis:"",ellipsisWidth:0,limit:i}).index,"widthToIndex"),m=g((r,i,t)=>O(r.slice(0,i),t),"indexToWidth"),B=g((r,i,t={})=>{if(typeof r!="string")throw new TypeError(`Expected \`input\` to be a string, got ${typeof r}`);if(typeof i!="number")throw new TypeError(`Expected \`limit\` to be a number, got ${typeof i}`);if(r===""||i<=0)return"";const e=r.normalize("NFC"),{ellipsis:d=b,position:w="end",preferTruncationOnSpace:l=!1}=t;let o=t.ellipsisWidth??d===b?1:void 0;o??=x(d,{...t.width,ellipsis:"",ellipsisWidth:0,limit:Number.POSITIVE_INFINITY}).width;const{width:n}=x(e,{...t.width,ellipsis:d,ellipsisWidth:o});if(n<=i)return e;switch(w){case"end":{if(l){const p=i-o,a=f(e,p,t.width),s=u(e,a),c=m(e,s,t.width);return h(e,0,c,{width:t.width})+d}return h(e,0,i-o,{width:t.width})+d}case"middle":{const p=Math.floor(i/2),a=Math.max(0,i-o),s=Math.min(p,a),c=Math.max(0,a-s);if(l){const y=f(e,s,t.width),I=u(e,y),E=m(e,I,t.width),W=n-c,S=f(e,W,t.width),v=u(e,S,!0),M=m(e,v,t.width);return h(e,0,E,{width:t.width})+d+h(e,M,n,{width:t.width}).trim()}return h(e,0,s,{width:t.width})+d+h(e,n-c,n,{width:t.width})}case"start":{if(l){const p=n-i+o,a=f(e,p,t.width),s=u(e,a,!0),c=m(e,s,t.width);return d+h(e,c,n,{width:t.width}).trim()}return d+h(e,n-i+o,n,{width:t.width})}default:throw new Error(`Invalid position: expected 'start', 'middle' or 'end', got '${w}'`)}},"truncate");export{B as truncate};

package/dist/utilities.d.ts

@@ -1,8 +1,35 @@
-import { a as IntervalArray } from "./packem_shared/types.d-BVNv675q.js";
+import { a as IntervalArray } from "./packem_shared/types.d-NJ4vcG-A.js";
 export { L as LRUCache } from "./packem_shared/lru-cache.d-BsP6kbVJ.js";
+/**
+* Escapes characters with special meaning in regular expressions.
+* @param char The string to escape.
+* @returns The escaped string.
+*/
 declare const escapeRegExp: (char: string) => string;
+/**
+* Checks if a number falls within any of the specified intervals.
+* @param number_ The number to check.
+* @param ranges An array of intervals [start, end].
+* @returns True if the number is within any interval, false otherwise.
+*/
 declare const inRange: (number_: number, ranges: IntervalArray) => boolean;
+/**
+* Checks if a string contains Chinese characters (Han script).
+* @param char The string to check.
+* @returns True if the string contains Chinese characters, false otherwise.
+*/
 declare const hasChinese: (char: string) => boolean;
+/**
+* Checks if a string contains punctuation or space characters.
+* @param char The string to check.
+* @returns True if the string contains punctuation or space, false otherwise.
+*/
 declare const hasPunctuationOrSpace: (char: string) => boolean;
+/**
+* Finds all occurrences of a set of substrings within a source string and returns their start/end indices.
+* @param source The string to search within.
+* @param needles An array of strings to search for.
+* @returns An array of intervals [start, end] for each occurrence.
+*/
 declare const findStringOccurrences: (source: string, needles: string[]) => IntervalArray;
 export { escapeRegExp, findStringOccurrences, hasChinese, hasPunctuationOrSpace, inRange };

package/dist/utilities.js

@@ -1,52 +1 @@
-export { default as LRUCache } from './packem_shared/LRUCache-3r3SovvR.js';
-
-const RE_REGEXP_SPECIAL = /[.*+?^${}()|[\]\\]/g;
-const RE_CHINESE = /[\u2E80-\u2E99\u2E9B-\u2EF3\u2F00-\u2FD5\u3005\u3007\u3021-\u3029\u3038-\u303B\u3400-\u4DBF\u4E00-\u9FFC\uF900-\uFA6D\uFA70-\uFAD9]|\uD81B[\uDFF0\uDFF1]|[\uD840-\uD868\uD86A-\uD86C\uD86F-\uD872\uD874-\uD879\uD880-\uD883][\uDC00-\uDFFF]|\uD869[\uDC00-\uDEDD\uDF00-\uDFFF]|\uD86D[\uDC00-\uDF34\uDF40-\uDFFF]|\uD86E[\uDC00-\uDC1D\uDC20-\uDFFF]|\uD873[\uDC00-\uDEA1\uDEB0-\uDFFF]|\uD87A[\uDC00-\uDFE0]|\uD87E[\uDC00-\uDE1D]|\uD884[\uDC00-\uDF4A]/;
-const RE_PUNCTUATION_OR_SPACE = /[\p{P}\p{Z}]/u;
-const escapeRegExp = (char) => (
-  // $& means the whole matched string
-  char.replaceAll(RE_REGEXP_SPECIAL, String.raw`\$&`)
-);
-const inRange = (number_, ranges) => ranges.some((range) => number_ >= range[0] && number_ <= range[1]);
-const hasChinese = (char) => RE_CHINESE.test(char);
-const hasPunctuationOrSpace = (char) => RE_PUNCTUATION_OR_SPACE.test(char);
-const findStringOccurrences = (source, needles) => {
-  const ranges = [];
-  if (!Array.isArray(needles)) {
-    return ranges;
-  }
-  needles.forEach((needle) => {
-    if (typeof needle !== "string" || needle.length === 0) {
-      return;
-    }
-    let startIndex = 0;
-    let index;
-    while ((index = source.indexOf(needle, startIndex)) > -1) {
-      const end = index + needle.length - 1;
-      ranges.push([index, end]);
-      startIndex = index + 1;
-    }
-  });
-  if (ranges.length === 0) {
-    return [];
-  }
-  ranges.sort((a, b) => a[0] - b[0]);
-  const merged = [];
-  let currentRange;
-  for (const range of ranges) {
-    if (currentRange === void 0) {
-      currentRange = [...range];
-    } else if (range[0] <= currentRange[1] + 1) {
-      currentRange[1] = Math.max(currentRange[1], range[1]);
-    } else {
-      merged.push(currentRange);
-      currentRange = [...range];
-    }
-  }
-  if (currentRange !== void 0) {
-    merged.push(currentRange);
-  }
-  return merged;
-};
-
-export { escapeRegExp, findStringOccurrences, hasChinese, hasPunctuationOrSpace, inRange };
+var i=Object.defineProperty;var c=(u,t)=>i(u,"name",{value:t,configurable:!0});import{default as B}from"./packem_shared/LRUCache-Bjo6gsbC.js";var p=Object.defineProperty,n=c((u,t)=>p(u,"name",{value:t,configurable:!0}),"D");const E=/[.*+?^${}()|[\]\\]/g,f=/[\u2E80-\u2E99\u2E9B-\u2EF3\u2F00-\u2FD5\u3005\u3007\u3021-\u3029\u3038-\u303B\u3400-\u4DBF\u4E00-\u9FFC\uF900-\uFA6D\uFA70-\uFAD9]|\uD81B[\uDFF0\uDFF1]|[\uD840-\uD868\uD86A-\uD86C\uD86F-\uD872\uD874-\uD879\uD880-\uD883][\uDC00-\uDFFF]|\uD869[\uDC00-\uDEDD\uDF00-\uDFFF]|\uD86D[\uDC00-\uDF34\uDF40-\uDFFF]|\uD86E[\uDC00-\uDC1D\uDC20-\uDFFF]|\uD873[\uDC00-\uDEA1\uDEB0-\uDFFF]|\uD87A[\uDC00-\uDFE0]|\uD87E[\uDC00-\uDE1D]|\uD884[\uDC00-\uDF4A]/,h=/[\p{P}\p{Z}]/u,g=n(u=>u.replaceAll(E,String.raw`\$&`),"escapeRegExp"),l=n((u,t)=>t.some(F=>u>=F[0]&&u<=F[1]),"inRange"),A=n(u=>f.test(u),"hasChinese"),d=n(u=>h.test(u),"hasPunctuationOrSpace"),x=n((u,t)=>{const F=[];if(!Array.isArray(t))return F;if(t.forEach(D=>{if(typeof D!="string"||D.length===0)return;let r=0,a;for(;(a=u.indexOf(D,r))>-1;){const o=a+D.length-1;F.push([a,o]),r=a+1}}),F.length===0)return[];F.sort((D,r)=>D[0]-r[0]);const s=[];let e;for(const D of F)e===void 0?e=[...D]:D[0]<=e[1]+1?e[1]=Math.max(e[1],D[1]):(s.push(e),e=[...D]);return e!==void 0&&s.push(e),s},"findStringOccurrences");export{B as LRUCache,g as escapeRegExp,x as findStringOccurrences,A as hasChinese,d as hasPunctuationOrSpace,l as inRange};

package/dist/word-similarity-sort.d.ts

@@ -1,6 +1,40 @@
+/** Options for {@linkcode wordSimilaritySort}. */
 interface WordSimilaritySortOptions {
   caseSensitive?: boolean;
   compareFunction?: (a: string, b: string) => number;
 }
+/**
+* Sorts a string-array by similarity to a given string.
+*
+* By default, calculates the distance between words using the
+* {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
+* @example Basic usage
+*
+* ```ts
+* import { wordSimilaritySort } from "@visulima/string";
+* import assert from "node:assert";
+*
+* const possibleWords = ["length", "size", "blah", "help"];
+* const suggestions = wordSimilaritySort("hep", possibleWords);
+*
+* assert.deepStrictEqual(suggestions, ["help", "size", "blah", "length"]);
+* ```
+* @example Case-sensitive sorting
+*
+* ```ts
+* import { wordSimilaritySort } from "@visulima/string";
+* import assert from "node:assert";
+*
+* const possibleWords = ["length", "Size", "blah", "HELP"];
+* const suggestions = wordSimilaritySort("hep", possibleWords, { caseSensitive: true });
+*
+* assert.deepStrictEqual(suggestions, ["Size", "blah", "HELP", "length"]);
+* ```
+* @param givenWord The string to measure distance against.
+* @param possibleWords The string-array that will be sorted. This array will
+* not be mutated, but the sorted copy will be returned.
+* @param options Options for the sort.
+* @returns A sorted copy of `possibleWords`.
+*/
 declare const wordSimilaritySort: (givenWord: string, possibleWords: ReadonlyArray<string>, options?: WordSimilaritySortOptions) => string[];
 export { WordSimilaritySortOptions, wordSimilaritySort };

package/dist/word-similarity-sort.js

@@ -1,22 +1 @@
-import { distance } from './packem_shared/closest-IHuSvnSn.js';
-
-const wordSimilaritySort = (givenWord, possibleWords, options) => {
-  const { caseSensitive = false, compareFunction = distance } = options ?? {};
-  const processedGivenWord = caseSensitive ? givenWord : givenWord.toLowerCase();
-  const wordsWithDistances = possibleWords.map((word) => {
-    const processedWord = caseSensitive ? word : word.toLowerCase();
-    return {
-      distance: compareFunction(processedGivenWord, processedWord),
-      originalWord: word
-    };
-  });
-  wordsWithDistances.sort((a, b) => {
-    if (a.distance !== b.distance) {
-      return a.distance - b.distance;
-    }
-    return a.originalWord.localeCompare(b.originalWord);
-  });
-  return wordsWithDistances.map((item) => item.originalWord);
-};
-
-export { wordSimilaritySort };
+var l=Object.defineProperty;var n=(e,r)=>l(e,"name",{value:r,configurable:!0});import{distance as m}from"./packem_shared/closest-uarbVSbs.js";var p=Object.defineProperty,u=n((e,r)=>p(e,"name",{value:r,configurable:!0}),"s");const f=u((e,r,s)=>{const{caseSensitive:i=!1,compareFunction:c=m}=s??{},d=i?e:e.toLowerCase(),t=r.map(o=>{const a=i?o:o.toLowerCase();return{distance:c(d,a),originalWord:o}});return t.sort((o,a)=>o.distance!==a.distance?o.distance-a.distance:o.originalWord.localeCompare(a.originalWord)),t.map(o=>o.originalWord)},"wordSimilaritySort");export{f as wordSimilaritySort};

package/dist/word-wrap.d.ts

@@ -1,14 +1,58 @@
+/**
+* Enum representing different wrapping strategies for text
+*/
 declare const WrapMode: {
+  /**
+  * Breaks words at character boundaries to fit the width
+  */
   readonly BREAK_AT_CHARACTERS: "BREAK_AT_CHARACTERS";
+  /**
+  * Breaks lines at word boundaries. If a word is longer than the width, it will be broken.
+  */
   readonly BREAK_WORDS: "BREAK_WORDS";
+  /**
+  * Preserves word boundaries, words are kept intact even if they exceed width
+  */
   readonly PRESERVE_WORDS: "PRESERVE_WORDS";
+  /**
+  * Enforces strict adherence to the width limit by breaking at exact width
+  */
   readonly STRICT_WIDTH: "STRICT_WIDTH";
 };
+/**
+* Word wrap options interface with detailed documentation
+*/
 interface WordWrapOptions {
+  /**
+  * Whether to remove zero-width characters from the string.
+  * @default true
+  */
   removeZeroWidthCharacters?: boolean;
+  /**
+  * Whether to trim whitespace from wrapped lines.
+  * @default true
+  */
   trim?: boolean;
+  /**
+  * Maximum width of each line in visible characters.
+  * @default 80
+  */
   width?: number;
+  /**
+  * Controls how text wrapping is handled at width boundaries.
+  * - PRESERVE_WORDS: Words are kept intact even if they exceed width (default)
+  * - BREAK_AT_CHARACTERS: Words are broken at character boundaries to fit width
+  * - STRICT_WIDTH: Forces breaking exactly at width limit, always
+  * - BREAK_WORDS: Breaks at word boundaries, but breaks words if they are too long
+  * @default WrapMode.PRESERVE_WORDS
+  */
   wrapMode?: keyof typeof WrapMode;
 }
+/**
+* Wraps text using multiple wrapping strategies.
+* @param string The string to wrap
+* @param options Wrapping options
+* @returns The wrapped string
+*/
 declare const wordWrap: (string: string, options?: WordWrapOptions) => string;
 export { WordWrapOptions, WrapMode, wordWrap };