@visulima/string 3.0.0-alpha.10 → 3.0.0-alpha.12

package/dist/case/title-case.d.ts

@@ -1,5 +1,15 @@
-import { C as CaseOptions, T as TitleCase } from "../packem_shared/types.d-DfgbcNKh.js";
-import "../packem_shared/types.d-BVNv675q.js";
+import { C as CaseOptions, T as TitleCase } from "../packem_shared/types.d-FOLSY2Tc.js";
+import "../packem_shared/types.d-NJ4vcG-A.js";
 import "../packem_shared/lru-cache.d-BsP6kbVJ.js";
+/**
+* With Title Case all words are capitalized, except for minor words.
+* @example
+* ```typescript
+* titleCase("this-IS-aTitle") // => "This is a Title"
+* titleCase("XMLHttpRequest") // => "XML Http Request"
+* titleCase("AJAXRequest") // => "AJAX Request"
+* titleCase("QueryXML123String") // => "Query XML 123 String"
+* ```
+*/
 declare function titleCase<T extends string = string>(value?: T, options?: CaseOptions): TitleCase<T>;
 export { titleCase as default };

package/dist/case/title-case.js

@@ -1,40 +1 @@
-import LRUCache from '../packem_shared/LRUCache-3r3SovvR.js';
-import { splitByCase } from './split-by-case.js';
-import upperFirst from './upper-first.js';
-import { g as generateCacheKey } from '../packem_shared/generate-cache-key-DdayDfjV.js';
-import { n as normalizeGermanEszett } from '../packem_shared/normalize-german-eszett-4p3yKEzn.js';
-
-const defaultCacheStore = new LRUCache(1e3);
-function titleCase(value, options) {
-  if (typeof value !== "string") {
-    return "";
-  }
-  const shouldCache = options?.cache ?? false;
-  const cacheStore = options?.cacheStore ?? defaultCacheStore;
-  let cacheKey;
-  if (shouldCache) {
-    cacheKey = generateCacheKey(value, options);
-  }
-  if (shouldCache && cacheKey && cacheStore.has(cacheKey)) {
-    return cacheStore.get(cacheKey);
-  }
-  const result = splitByCase(value, {
-    handleAnsi: options?.handleAnsi,
-    handleEmoji: options?.handleEmoji,
-    knownAcronyms: options?.knownAcronyms,
-    locale: options?.locale,
-    normalize: options?.normalize,
-    separators: void 0,
-    stripAnsi: options?.stripAnsi,
-    stripEmoji: options?.stripEmoji
-  }).map((word) => {
-    const normalized = options?.locale?.startsWith("de") ? normalizeGermanEszett(word) : word;
-    return upperFirst(options?.locale ? normalized.toLocaleLowerCase(options.locale) : normalized.toLowerCase(), { locale: options?.locale });
-  }).join(" ");
-  if (shouldCache && cacheKey) {
-    cacheStore.set(cacheKey, result);
-  }
-  return result;
-}
-
-export { titleCase as default };
+var c=Object.defineProperty;var i=(r,o)=>c(r,"name",{value:o,configurable:!0});import m from"../packem_shared/LRUCache-Bjo6gsbC.js";import{splitByCase as p}from"./split-by-case.js";import f from"./upper-first.js";import{a as u}from"../packem_shared/generate-cache-key-DPByFaMH.js";import{l as d}from"../packem_shared/normalize-german-eszett-AKfdw2MZ.js";var h=Object.defineProperty,j=i((r,o)=>h(r,"name",{value:o,configurable:!0}),"c");const A=new m(1e3);function w(r,o){if(typeof r!="string")return"";const a=o?.cache??!1,e=o?.cacheStore??A;let t;if(a&&(t=u(r,o)),a&&t&&e.has(t))return e.get(t);const n=p(r,{handleAnsi:o?.handleAnsi,handleEmoji:o?.handleEmoji,knownAcronyms:o?.knownAcronyms,locale:o?.locale,normalize:o?.normalize,separators:void 0,stripAnsi:o?.stripAnsi,stripEmoji:o?.stripEmoji}).map(l=>{const s=o?.locale?.startsWith("de")?d(l):l;return f(o?.locale?s.toLocaleLowerCase(o.locale):s.toLowerCase(),{locale:o?.locale})}).join(" ");return a&&t&&e.set(t,n),n}i(w,"g");j(w,"titleCase");export{w as default};

package/dist/case/train-case.d.ts

@@ -1,5 +1,17 @@
-import { C as CaseOptions, j as TrainCase } from "../packem_shared/types.d-DfgbcNKh.js";
-import "../packem_shared/types.d-BVNv675q.js";
+import { C as CaseOptions, j as TrainCase } from "../packem_shared/types.d-FOLSY2Tc.js";
+import "../packem_shared/types.d-NJ4vcG-A.js";
 import "../packem_shared/lru-cache.d-BsP6kbVJ.js";
+/**
+* Converts a string to Train-Case.
+* @example
+* ```typescript
+* trainCase("foo bar") // => "Foo-Bar"
+* trainCase("foo-bar") // => "Foo-Bar"
+* trainCase("foo_bar") // => "Foo-Bar"
+* trainCase("XMLHttpRequest") // => "XML-Http-Request"
+* trainCase("AJAXRequest") // => "AJAX-Request"
+* trainCase("QueryXML123String") // => "Query-XML-123-String"
+* ```
+*/
 declare const trainCase: <T extends string = string>(value?: T, options?: CaseOptions) => TrainCase<T>;
 export { trainCase as default };

package/dist/case/train-case.js

@@ -1,40 +1 @@
-import LRUCache from '../packem_shared/LRUCache-3r3SovvR.js';
-import { splitByCase } from './split-by-case.js';
-import upperFirst from './upper-first.js';
-import { g as generateCacheKey } from '../packem_shared/generate-cache-key-DdayDfjV.js';
-import joinSegments from '../packem_shared/joinSegments-CvxSgKz0.js';
-
-const defaultCacheStore = new LRUCache(1e3);
-const trainCase = (value, options) => {
-  if (typeof value !== "string") {
-    return "";
-  }
-  const shouldCache = options?.cache ?? false;
-  const cacheStore = options?.cacheStore ?? defaultCacheStore;
-  let cacheKey;
-  if (shouldCache) {
-    cacheKey = generateCacheKey(value, options);
-  }
-  if (shouldCache && cacheKey && cacheStore.has(cacheKey)) {
-    return cacheStore.get(cacheKey);
-  }
-  const result = joinSegments(
-    splitByCase(value, {
-      handleAnsi: options?.handleAnsi,
-      handleEmoji: options?.handleEmoji,
-      knownAcronyms: options?.knownAcronyms,
-      locale: options?.locale,
-      normalize: options?.normalize,
-      separators: void 0,
-      stripAnsi: options?.stripAnsi,
-      stripEmoji: options?.stripEmoji
-    }).map((p) => upperFirst(p, { locale: options?.locale })),
-    "-"
-  );
-  if (shouldCache && cacheKey) {
-    cacheStore.set(cacheKey, result);
-  }
-  return result;
-};
-
-export { trainCase as default };
+var m=Object.defineProperty;var e=(o,r)=>m(o,"name",{value:r,configurable:!0});import l from"../packem_shared/LRUCache-Bjo6gsbC.js";import{splitByCase as p}from"./split-by-case.js";import c from"./upper-first.js";import{a as f}from"../packem_shared/generate-cache-key-DPByFaMH.js";import h from"../packem_shared/joinSegments-D27SxoCV.js";var d=Object.defineProperty,u=e((o,r)=>d(o,"name",{value:r,configurable:!0}),"i");const A=new l(1e3),C=u((o,r)=>{if(typeof o!="string")return"";const n=r?.cache??!1,i=r?.cacheStore??A;let t;if(n&&(t=f(o,r)),n&&t&&i.has(t))return i.get(t);const a=h(p(o,{handleAnsi:r?.handleAnsi,handleEmoji:r?.handleEmoji,knownAcronyms:r?.knownAcronyms,locale:r?.locale,normalize:r?.normalize,separators:void 0,stripAnsi:r?.stripAnsi,stripEmoji:r?.stripEmoji}).map(s=>c(s,{locale:r?.locale})),"-");return n&&t&&i.set(t,a),a},"trainCase");export{C as default};

package/dist/case/upper-first.d.ts

@@ -1,5 +1,16 @@
-import { L as LocaleOptions, U as UpperFirst } from "../packem_shared/types.d-DfgbcNKh.js";
-import "../packem_shared/types.d-BVNv675q.js";
+import { L as LocaleOptions, U as UpperFirst } from "../packem_shared/types.d-FOLSY2Tc.js";
+import "../packem_shared/types.d-NJ4vcG-A.js";
 import "../packem_shared/lru-cache.d-BsP6kbVJ.js";
+/**
+* Converts first character to upper case.
+* @param value The string to convert.
+* @param options Options for case conversion.
+* @returns The string with its first character converted to uppercase.
+* @example
+* ```typescript
+* upperFirst("hello world!") // => "Hello world!"
+* upperFirst("istanbul", { locale: "tr" }) // => "İstanbul"
+* ```
+*/
 declare const upperFirst: <T extends string = string>(value?: T, options?: LocaleOptions) => UpperFirst<T>;
 export { upperFirst as default };

package/dist/case/upper-first.js

@@ -1,9 +1 @@
-const upperFirst = (value, options) => {
-  if (typeof value !== "string" || value === "") {
-    return "";
-  }
-  const firstChar = options?.locale ? value[0].toLocaleUpperCase(options.locale) : value[0].toUpperCase();
-  return firstChar + value.slice(1);
-};
-
-export { upperFirst as default };
+var p=Object.defineProperty;var o=(e,a)=>p(e,"name",{value:a,configurable:!0});var t=Object.defineProperty,l=o((e,a)=>t(e,"name",{value:a,configurable:!0}),"s");const s=l((e,a)=>typeof e!="string"||e===""?"":(a?.locale?e[0].toLocaleUpperCase(a.locale):e[0].toUpperCase())+e.slice(1),"upperFirst");export{s as default};

package/dist/closest-string.d.ts

@@ -1,6 +1,38 @@
+/** Options for {@linkcode closestString}. */
 interface ClosestStringOptions {
+  /**
+  * Whether the distance should include case.
+  * @default {false}
+  */
   caseSensitive?: boolean;
+  /**
+  * A custom comparison function to use for comparing strings.
+  * @param a The first string for comparison.
+  * @param b The second string for comparison.
+  * @returns The distance between the two strings.
+  * @default {levenshteinDistance}
+  */
   compareFn?: (a: string, b: string) => number;
 }
+/**
+* Finds the most similar string from an array of strings.
+*
+* By default, calculates the distance between words using the
+* {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
+* @example Usage
+* ```ts
+* import { closestString } from "@visulima/string";
+* import assert from "node:assert";
+*
+* const possibleWords = ["length", "size", "blah", "help"];
+* const suggestion = closestString("hep", possibleWords);
+*
+* assert.deepStrictEqual(suggestion, "help");
+* ```
+* @param givenWord The string to measure distance against
+* @param possibleWords The string-array to pick the closest string from
+* @param options The options for the comparison.
+* @returns The closest string from `possibleWords`, or `undefined` if `possibleWords` is empty (though the function throws in this case).
+*/
 declare const closestString: (givenWord: string, possibleWords: ReadonlyArray<string>, options?: ClosestStringOptions) => string | undefined;
 export { ClosestStringOptions, closestString };

package/dist/closest-string.js

@@ -1,22 +1 @@
-import { distance } from './packem_shared/closest-IHuSvnSn.js';
-
-const closestString = (givenWord, possibleWords, options) => {
-  if (possibleWords.length === 0) {
-    throw new TypeError("When using closestString(), the possibleWords array must contain at least one word");
-  }
-  const { caseSensitive, compareFn: compareFunction = distance } = { ...options };
-  const normalizedGivenWord = caseSensitive ? givenWord : givenWord.toLowerCase();
-  let nearestWord = possibleWords[0] ?? void 0;
-  let closestStringDistance = Infinity;
-  for (const possibleWord of possibleWords) {
-    const each = possibleWord;
-    const distance = caseSensitive ? compareFunction(normalizedGivenWord, each) : compareFunction(normalizedGivenWord, each.toLowerCase());
-    if (distance < closestStringDistance) {
-      nearestWord = each;
-      closestStringDistance = distance;
-    }
-  }
-  return nearestWord;
-};
-
-export { closestString };
+var g=Object.defineProperty;var l=(t,e)=>g(t,"name",{value:e,configurable:!0});import{distance as p}from"./packem_shared/closest-uarbVSbs.js";var u=Object.defineProperty,m=l((t,e)=>u(t,"name",{value:e,configurable:!0}),"l");const h=m((t,e,f)=>{if(e.length===0)throw new TypeError("When using closestString(), the possibleWords array must contain at least one word");const{caseSensitive:r,compareFn:s=p}={...f},n=r?t:t.toLowerCase();let a=e[0]??void 0,i=1/0;for(const d of e){const o=d,c=r?s(n,o):s(n,o.toLowerCase());c<i&&(a=o,i=c)}return a},"closestString");export{h as closestString};

package/dist/compare-similarity.d.ts

@@ -1,6 +1,43 @@
+/** Options for {@linkcode compareSimilarity}. */
 interface CompareSimilarityOptions {
+  /**
+  * Whether the distance should include case.
+  * @default {false}
+  */
   caseSensitive?: boolean;
+  /**
+  * A custom comparison function to use for comparing strings.
+  * @param a The first string for comparison.
+  * @param b The second string for comparison.
+  * @returns The distance between the two strings.
+  * @default {levenshteinDistance}
+  */
   compareFn?: (a: string, b: string) => number;
 }
-declare const compareSimilarity: (givenWord: string, options?: CompareSimilarityOptions) => (a: string, b: string) => number;
+/**
+* Takes a string and generates a comparator function to determine which of two
+* strings is more similar to the given one.
+*
+* By default, calculates the distance between words using the
+* {@link https://en.wikipedia.org/wiki/Levenshtein_distance | Levenshtein distance}.
+* @param givenWord The string to measure distance against.
+* @param options Options for the sort.
+* @returns The difference in distance. This will be a negative number if `a`
+* is more similar to `givenWord` than `b`, a positive number if `b` is more
+* similar, or `0` if they are equally similar.
+* @example Usage
+*
+* Most-similar words will be at the start of the array.
+*
+* ```ts
+* import { compareSimilarity } from "@visulima/string";
+* import assert from "node:assert";
+*
+* const words = ["hi", "hello", "help"];
+* const sortedWords = words.toSorted(compareSimilarity("hep"));
+*
+* assert.deepStrictEqual(sortedWords, ["help", "hi", "hello"]);
+* ```
+*/
+declare const compareSimilarity: (givenWord: string, options?: CompareSimilarityOptions) => ((a: string, b: string) => number);
 export { CompareSimilarityOptions, compareSimilarity };

package/dist/compare-similarity.js

@@ -1,12 +1 @@
-import { distance } from './packem_shared/closest-IHuSvnSn.js';
-
-const compareSimilarity = (givenWord, options) => {
-  const { compareFn: compareFunction = distance } = { ...options };
-  if (options?.caseSensitive) {
-    return (a, b) => compareFunction(givenWord, a) - compareFunction(givenWord, b);
-  }
-  const normalizedGivenWord = givenWord.toLowerCase();
-  return (a, b) => compareFunction(normalizedGivenWord, a.toLowerCase()) - compareFunction(normalizedGivenWord, b.toLowerCase());
-};
-
-export { compareSimilarity };
+var s=Object.defineProperty;var n=(e,r)=>s(e,"name",{value:r,configurable:!0});import{distance as c}from"./packem_shared/closest-uarbVSbs.js";var m=Object.defineProperty,p=n((e,r)=>m(e,"name",{value:r,configurable:!0}),"a");const l=p((e,r)=>{const{compareFn:o=c}={...r};if(r?.caseSensitive)return(t,a)=>o(e,t)-o(e,a);const i=e.toLowerCase();return(t,a)=>o(i,t.toLowerCase())-o(i,a.toLowerCase())},"compareSimilarity");export{l as compareSimilarity};

package/dist/get-string-truncated-width.d.ts

@@ -1,23 +1,174 @@
+/**
+* Configuration options for string width calculation and truncation.
+* @example
+* ```typescript
+* // Basic usage with defaults
+* const options: StringTruncatedWidthOptions = {};
+*
+* // Custom character widths
+* const options: StringTruncatedWidthOptions = {
+*   regularWidth: 2,
+*   emojiWidth: 3,
+*   tabWidth: 4
+* };
+*
+* // Truncation settings
+* const options: StringTruncatedWidthOptions = {
+*   limit: 10,
+*   ellipsis: '...',
+*   ellipsisWidth: 3
+* };
+* ```
+*/
 interface StringTruncatedWidthOptions {
+  /**
+  * Count [ambiguous width characters](https://www.unicode.org/reports/tr11/#Ambiguous) as having narrow width (count of 1 (regular)) instead of wide width (count of 2 (wide)).
+  * @default false
+  */
   ambiguousIsNarrow?: boolean;
+  /**
+  * Width of ANSI escape sequences
+  * @default 0
+  */
   ansiWidth?: number;
+  /**
+  * Width of control characters
+  * @default 0
+  */
   controlWidth?: number;
+  /**
+  * Whether to count ANSI escape codes in width calculation
+  * @default false
+  */
   countAnsiEscapeCodes?: boolean;
+  /**
+  * 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;
+  /**
+  * Width of emoji characters
+  * @default 2
+  */
   emojiWidth?: number;
+  /**
+  * Width of full-width characters
+  * @default 2
+  */
   fullWidth?: number;
+  /**
+  * Width of half-width characters
+  * @default 1
+  */
   halfWidth?: number;
+  /**
+  * Maximum width limit for the string
+  * @default Infinity
+  */
   limit?: number;
+  /**
+  * Width of regular characters
+  * @default 1
+  */
   regularWidth?: number;
+  /**
+  * Width of tab characters
+  * @default 8
+  */
   tabWidth?: number;
+  /**
+  * Width of wide characters
+  * @default 2
+  */
   wideWidth?: number;
 }
+/**
+* Result object returned by getStringTruncatedWidth containing width calculation and the truncation details.
+* @example
+* ```typescript
+* // No truncation
+* const result: StringTruncatedWidthResult = {
+*   width: 5,        // Total visual width
+*   truncated: false, // String was not truncated
+*   ellipsed: false, // No ellipsis added
+*   index: 5,        // Full string length
+* };
+*
+* // With truncation
+* const result: StringTruncatedWidthResult = {
+*   width: 8,        // Width including ellipsis
+*   truncated: true,  // String was truncated
+*   ellipsed: true,   // Ellipsis was added
+*   index: 5,         // Truncation point
+* };
+* ```
+*/
 interface StringTruncatedWidthResult {
+  /**
+  * Whether an ellipsis was added
+  */
   ellipsed: boolean;
+  /**
+  * The index at which truncation occurred (if any)
+  */
   index: number;
+  /**
+  * Whether the string was truncated
+  */
   truncated: boolean;
+  /**
+  * The calculated width of the string
+  */
   width: number;
 }
+/**
+* Calculate the visual width of a string with optional truncation, handling various Unicode character types.
+* @example
+* ```typescript
+* // Basic width calculation
+* getStringTruncatedWidth('hello');
+* // => { width: 5, truncated: false, ellipsed: false, index: 5 }
+*
+* // With truncation
+* getStringTruncatedWidth('hello world', {
+*   limit: 8,
+*   ellipsis: '...'
+* });
+* // => { width: 8, truncated: true, ellipsed: true, index: 5 }
+*
+* // With custom character widths
+* getStringTruncatedWidth('あいう', {
+*   fullWidth: 2,
+*   ambiguousIsNarrow: true
+* });
+* // => { width: 6, truncated: false, ellipsed: false, index: 3 }
+*
+* // With combining characters
+* getStringTruncatedWidth('e\u0301'); // Latin e with acute
+* // => { width: 1, truncated: false, ellipsed: false, index: 2 }
+*
+* getStringTruncatedWidth('ก\u0e31'); // Thai character with vowel mark
+* // => { width: 1, truncated: false, ellipsed: false, index: 2 }
+* ```
+*
+* Features:
+* - Full Unicode support including combining marks from various scripts
+* - Accurate width calculation for emoji sequences
+* - ANSI escape code handling
+* - Customizable character widths
+* - Optional string truncation with ellipsis
+* @param input The string to calculate the width for
+* @param options Configuration options for width calculation and truncation
+* @returns Result object containing:
+* - width: The calculated visual width of the string
+* - truncated: Whether the string was truncated
+* - ellipsed: Whether an ellipsis was added
+* - index: The index at which truncation occurred (if any)
+*/
 declare const getStringTruncatedWidth: (input: string, options?: StringTruncatedWidthOptions) => StringTruncatedWidthResult;
 export { StringTruncatedWidthOptions, StringTruncatedWidthResult, getStringTruncatedWidth };