@visulima/string 3.0.0-alpha.9 → 3.1.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-CMNqA5bi.js";
+import "../packem_shared/types.d-LgsTR37y.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 };
+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{a as p}from"../packem_shared/generate-cache-key-B_0X7MKm.js";import{a as f}from"../packem_shared/normalize-german-eszett-hNMwtGjd.js";const d=new e(1e3);function y(a,o){if(typeof a!="string")return"";const t=o?.cache??!1,s=o?.cacheStore??d;let r;if(t&&(r=p(a,o)),t&&r&&s.has(r))return s.get(r);const i=c(a,{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(n=>{const l=o?.locale?.startsWith("de")?f(n):n;return m(o?.locale?l.toLocaleLowerCase(o.locale):l.toLowerCase(),{locale:o?.locale})}).join(" ");return t&&r&&s.set(r,i),i}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-CMNqA5bi.js";
+import "../packem_shared/types.d-LgsTR37y.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 };
+import{i as m}from"../packem_shared/lru-cache-BtMSrYQJ.js";import{splitByCase as l}from"./split-by-case.js";import e from"./upper-first.js";import{a as p}from"../packem_shared/generate-cache-key-B_0X7MKm.js";import c from"../packem_shared/joinSegments-CaHT-45s.js";const f=new m(1e3),y=(t,o)=>{if(typeof t!="string")return"";const i=o?.cache??!1,n=o?.cacheStore??f;let r;if(i&&(r=p(t,o)),i&&r&&n.has(r))return n.get(r);const s=c(l(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(a=>e(a,{locale:o?.locale})),"-");return i&&r&&n.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-CMNqA5bi.js";
+import "../packem_shared/types.d-LgsTR37y.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,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 };
+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);
-  }
-  const normalizedGivenWord = givenWord.toLowerCase();
-  return (a, b) => compareFunction(normalizedGivenWord, a.toLowerCase()) - compareFunction(normalizedGivenWord, 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,58 @@
+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 };