@visulima/string 3.0.0-alpha.8 → 3.0.0

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

@@ -1,5 +1,14 @@
-import { C as CaseOptions, T as TitleCase } from "../packem_shared/types.d-DfgbcNKh.js";
-import "../packem_shared/types.d-BVNv675q.js";
-import "../packem_shared/lru-cache.d-BsP6kbVJ.js";
+import { b as CaseOptions, T as TitleCase } from "../packem_shared/types.d-fhe030jX.js";
+import "../packem_shared/types.d-CmNvyl4l.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,42 +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-DEB8-ZPT.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) => {
-    if (options?.locale?.startsWith("de")) {
-      word = normalizeGermanEszett(word);
-    }
-    return upperFirst(options?.locale ? word.toLocaleLowerCase(options.locale) : word.toLowerCase(), { locale: options?.locale });
-  }).join(" ");
-  if (shouldCache && cacheKey) {
-    cacheStore.set(cacheKey, result);
-  }
-  return result;
-}
-
-export { titleCase as default };
+import{i as e}from"../packem_shared/lru-cache-BtMSrYQJ.js";import{splitByCase as c}from"./split-by-case.js";import m from"./upper-first.js";import{n as p}from"../packem_shared/generate-cache-key-BqU1Cqwm.js";import{a as f}from"../packem_shared/normalize-german-eszett-hNMwtGjd.js";const d=new e(1e3);function y(t,o){if(typeof t!="string")return"";const a=o?.cache??!1,i=o?.cacheStore??d;let r;if(a&&(r=p(t,o)),a&&r&&i.has(r))return i.get(r);const n=c(t,{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(s=>{const l=o?.locale?.startsWith("de")?f(s):s;return m(o?.locale?l.toLocaleLowerCase(o.locale):l.toLowerCase(),{locale:o?.locale})}).join(" ");return a&&r&&i.set(r,n),n}export{y as default};

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

@@ -1,5 +1,16 @@
-import { C as CaseOptions, j as TrainCase } from "../packem_shared/types.d-DfgbcNKh.js";
-import "../packem_shared/types.d-BVNv675q.js";
-import "../packem_shared/lru-cache.d-BsP6kbVJ.js";
+import { b as CaseOptions, j as TrainCase } from "../packem_shared/types.d-fhe030jX.js";
+import "../packem_shared/types.d-CmNvyl4l.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-BStLas0c.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 };
+import{i as a}from"../packem_shared/lru-cache-BtMSrYQJ.js";import{splitByCase as l}from"./split-by-case.js";import e from"./upper-first.js";import{n as p}from"../packem_shared/generate-cache-key-BqU1Cqwm.js";import c from"../packem_shared/joinSegments-CaHT-45s.js";const f=new a(1e3),y=(n,o)=>{if(typeof n!="string")return"";const t=o?.cache??!1,i=o?.cacheStore??f;let r;if(t&&(r=p(n,o)),t&&r&&i.has(r))return i.get(r);const s=c(l(n,{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(m=>e(m,{locale:o?.locale})),"-");return t&&r&&i.set(r,s),s};export{y as default};

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

@@ -1,5 +1,15 @@
-import { L as LocaleOptions, U as UpperFirst } from "../packem_shared/types.d-DfgbcNKh.js";
-import "../packem_shared/types.d-BVNv675q.js";
-import "../packem_shared/lru-cache.d-BsP6kbVJ.js";
+import { L as LocaleOptions, U as UpperFirst } from "../packem_shared/types.d-fhe030jX.js";
+import "../packem_shared/types.d-CmNvyl4l.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 };
+const a=(e,o)=>typeof e!="string"||e===""?"":(o?.locale?e[0].toLocaleUpperCase(o.locale):e[0].toUpperCase())+e.slice(1);export{a 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,23 +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 };
-  if (!caseSensitive) {
-    givenWord = givenWord.toLowerCase();
-  }
-  let nearestWord = possibleWords[0] ?? void 0;
-  let closestStringDistance = Infinity;
-  for (const each of possibleWords) {
-    const distance = caseSensitive ? compareFunction(givenWord, each) : compareFunction(givenWord, each.toLowerCase());
-    if (distance < closestStringDistance) {
-      nearestWord = each;
-      closestStringDistance = distance;
-    }
-  }
-  return nearestWord;
-};
-
-export { closestString };
+import{distance as p}from"./packem_shared/closest-C6YDQs4m.js";const d=(s,o,l)=>{if(o.length===0)throw new TypeError("When using closestString(), the possibleWords array must contain at least one word");const{caseSensitive:e,compareFn:r=p}={...l},n=e?s:s.toLowerCase();let a=o[0]??void 0,i=1/0;for(const g of o){const t=g,c=e?r(n,t):r(n,t.toLowerCase());c<i&&(a=t,i=c)}return a};export{d 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;
 }
+/**
+* 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);
-  }
-  givenWord = givenWord.toLowerCase();
-  return (a, b) => compareFunction(givenWord, a.toLowerCase()) - compareFunction(givenWord, b.toLowerCase());
-};
-
-export { compareSimilarity };
+import{distance as i}from"./packem_shared/closest-C6YDQs4m.js";const n=(o,s)=>{const{compareFn:e=i}={...s};if(s?.caseSensitive)return(t,r)=>e(o,t)-e(o,r);const a=o.toLowerCase();return(t,r)=>e(a,t.toLowerCase())-e(a,r.toLowerCase())};export{n as compareSimilarity};

package/dist/count-occurrences.d.ts

@@ -0,0 +1,9 @@
+/**
+* Get the count of `substring` in `value`.
+* @param value Content to search in. Will be coerced to string.
+* @param substring Substring to look for, typically one character.
+* @returns Count of `substring`s in `value`.
+* @throws {TypeError} When substring is not a string or is empty.
+*/
+declare const countOccurrences: (value: unknown, substring: string) => number;
+export { countOccurrences };

package/dist/count-occurrences.js

@@ -0,0 +1 @@
+const i=(c,r)=>{const n=String(c);if(typeof r!="string")throw new TypeError("Expected character");if(r.length===0)throw new TypeError("Expected non-empty substring");let e=0,t=n.indexOf(r);for(;t!==-1;){e++;const o=t+r.length;if(o<=t)break;t=n.indexOf(r,o)}return e};export{i as countOccurrences};

package/dist/direction.d.ts

@@ -0,0 +1,7 @@
+/**
+* Detect the direction of text: left-to-right, right-to-left, or neutral.
+* @param value The string to analyze.
+* @returns The text direction: 'rtl' for right-to-left, 'ltr' for left-to-right, or 'neutral' for neutral.
+*/
+declare const direction: (value?: string) => "rtl" | "ltr" | "neutral";
+export { direction };

package/dist/direction.js

@@ -0,0 +1 @@
+const e="֑-߿יִ-﷽ﹰ-ﻼ",n="A-Za-zÀ-ÖØ-öø-ʸ̀-֐ࠀ-῿‎Ⰰ-﬜︀-﹯﻽-￿",o=new RegExp(`^[^${n}]*[${e}]`),s=new RegExp(`^[^${e}]*[${n}]`),c=(r="")=>{const t=r;return o.test(t)?"rtl":s.test(t)?"ltr":"neutral"};export{c as direction};

package/dist/east-asian-width.d.ts

@@ -0,0 +1,52 @@
+type WidthType = 'fullwidth' | 'halfwidth' | 'wide' | 'narrow' | 'neutral' | 'ambiguous';
+type Options = {
+  /**
+  Whether to treat an `'ambiguous'` character as wide.
+  	@default true
+  	@example
+  ```
+  import {eastAsianWidth} from 'get-east-asian-width';
+  	const codePoint = '⛣'.codePointAt(0);
+  	console.log(eastAsianWidth(codePoint));
+  //=> 1
+  	console.log(eastAsianWidth(codePoint, {ambiguousAsWide: true}));
+  //=> 2
+  ```
+  	> Ambiguous characters behave like wide or narrow characters depending on the context (language tag, script identification, associated font, source of data, or explicit markup; all can provide the context). __If the context cannot be established reliably, they should be treated as narrow characters by default.__
+  > - http://www.unicode.org/reports/tr11/
+  */
+  readonly ambiguousAsWide?: boolean;
+};
+/**
+Returns the width as a number for the given code point.
+
+@param codePoint - A Unicode code point.
+
+@example
+```
+import {eastAsianWidth} from 'get-east-asian-width';
+
+const codePoint = '字'.codePointAt(0);
+
+console.log(eastAsianWidth(codePoint));
+//=> 2
+```
+*/
+declare function eastAsianWidth(codePoint: number, options?: Options): 1 | 2;
+/**
+Returns the type of “East Asian Width” for the given code point.
+
+@param codePoint - A Unicode code point.
+
+@example
+```
+import {eastAsianWidthType} from 'get-east-asian-width';
+
+const codePoint = '字'.codePointAt(0);
+
+console.log(eastAsianWidthType(codePoint));
+//=> 'wide'
+```
+*/
+declare function eastAsianWidthType(codePoint: number): WidthType;
+export { type Options as EastAsianWidthOptions, type WidthType as EastAsianWidthType, eastAsianWidth, eastAsianWidthType };

package/dist/east-asian-width.js

@@ -0,0 +1 @@
+import{eastAsianWidth as e,eastAsianWidthType as i}from"./packem_shared/eastAsianWidth-DJV8Kqd-.js";export{e as eastAsianWidth,i as eastAsianWidthType};

package/dist/excerpt.d.ts

@@ -0,0 +1,25 @@
+import { TruncateOptions } from "./truncate.js";
+import "./get-string-truncated-width.js";
+/**
+* Truncates a sentence to be under the given character limit and strips HTML tags from it.
+* This function first removes all HTML tags and decodes HTML entities, then truncates
+* the resulting plain text to the specified character limit using the truncate function.
+* @example
+* ```typescript
+* excerpt('<p>Hello <strong>world</strong>!</p>', 10);
+* // => 'Hello worl…'
+*
+* excerpt('<div>This is a <em>long</em> text</div>', 20, { ellipsis: '...' });
+* // => 'This is a long text'
+* ```
+* @param html The HTML string to truncate
+* @param limit Maximum character limit for the truncated string
+* @param options Configuration options for truncation
+* @returns The truncated plain text string with HTML tags removed
+*/
+declare const excerpt: (html: string, limit: number, options?: ExcerptOptions) => string;
+/**
+* Options for the excerpt function
+*/
+type ExcerptOptions = Omit<TruncateOptions, "position">;
+export { ExcerptOptions, excerpt };