@js-utils-kit/string 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Sriman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.cjs

@@ -0,0 +1 @@
+function e(e){return e.replace(/^\w/,e=>e.toUpperCase())}function t(e,t=/\s+/){return e.split(t)}function n(e,n){return n?[...e].filter(e=>e===n).length:t(e).length}function r(e){return[...e].reduce((e,t)=>(e[t]=(e[t]||0)+1,e),{})}function i(e){return e?t(e,/\r\n|\r|\n/).length:0}function a(e,n){return n.length===0?0:t(e,n).length-1}function o(e){return t(e.trim()).length}function s(e,t=``){return e.replace(/[^\p{L}\p{N}\s]/gu,t)}function c(e){let n=t(e.trim()).map(e=>s(e)).filter(Boolean);if(n.length===0)return``;let r=Math.max(...n.map(e=>e.length)),i=n.filter(e=>e.length===r),a=[...new Set(i)];return a.length===1?a[0]:a}function l(e){let n=t(e).map(e=>s(e)).filter(Boolean);return n.length===0?0:n.reduce((e,t)=>Math.max(e,t.length),0)}function u(e,t,n=` `){return e.padStart(t,n)}function d(e,t,n=` `){return e.padEnd(t,n)}function f(e,t){return e.repeat(t)}function p(e){let n=t(e.trim()).map(e=>s(e)).filter(Boolean);if(n.length===0)return``;let r=Math.min(...n.map(e=>e.length)),i=n.filter(e=>e.length===r),a=[...new Set(i)];return a.length===1?a[0]:a}function m(e){let n=t(e.trim()).map(e=>s(e)).filter(Boolean);return n.length===0?0:n.reduce((e,t)=>Math.min(e,t.length),1/0)}const h=Object.assign(e=>e.trim(),{start:e=>e.trimStart(),end:e=>e.trimEnd(),normalizeWhitespace:e=>e.trim().replace(/\s+/g,` `)});function g(e,t,n=`...`){return t<=0?``:e.length<=t?e:n.length>=t?n.slice(0,t):e.trim().slice(0,t)+n}function _(e){return[...new Set(e)]}exports.capitalize=e,exports.countChars=n,exports.countFrequencies=r,exports.countLines=i,exports.countSubstring=a,exports.countWords=o,exports.longestWord=c,exports.longestWordLength=l,exports.padLeft=u,exports.padRight=d,exports.repeatString=f,exports.shortestWord=p,exports.shortestWordLength=m,exports.splitString=t,exports.stripSymbols=s,exports.trim=h,exports.truncate=g,exports.uniqueChars=_;var v=require(`@js-utils-kit/types`);Object.keys(v).forEach(function(e){e!==`default`&&!Object.prototype.hasOwnProperty.call(exports,e)&&Object.defineProperty(exports,e,{enumerable:!0,get:function(){return v[e]}})});

package/dist/index.d.cts

@@ -0,0 +1,413 @@
+import { Trim } from "@js-utils-kit/types";
+export * from "@js-utils-kit/types";
+
+//#region src/capitalize.d.ts
+
+/**
+ * Capitalizes the first character of a string using a regular expression.
+ *
+ * @returns The input string with its first character capitalized, or the original string if empty or not a string.
+ *
+ * @example
+ * ```ts
+ * capitalize("hello"); // "Hello"
+ * capitalize("world"); // "World"
+ * capitalize(""); // ""
+ * capitalize("a"); // "A"
+ * ```
+ */
+declare function capitalize(/** The string to capitalize */
+value: string): string;
+//#endregion
+//#region src/countChars.d.ts
+/**
+ * Counts characters in a string.
+ *
+ * @remarks
+ * - If `char` is provided, only that character’s occurrences are counted.
+ * - If `char` is omitted, the function counts the number of substrings returned by {@link splitString} (similar to a word count).
+ *
+ * @returns Number of characters or character occurrences.
+ *
+ * @example
+ * ```ts
+ * countChars("banana");       // 6
+ * countChars("banana", "a");  // 3
+ * countChars("banana", "n");  // 2
+ * ```
+ */
+declare function countChars(/** The input string. */
+str: string, /** Optional character to count. */
+char?: string): number;
+//#endregion
+//#region src/countFrequencies.d.ts
+/**
+ * Builds a frequency map of characters in a string.
+ *
+ * @remarks
+ * - Returns an object where keys are characters and values are counts.
+ * - Case-sensitive by default.
+ *
+ * @returns A mapping of each character to its frequency.
+ *
+ * @example
+ * ```ts
+ * countFrequencies("banana");
+ * // { b: 1, a: 3, n: 2 }
+ *
+ * countFrequencies("");
+ * // {}
+ * ```
+ */
+declare function countFrequencies(/** The input string. */
+str: string): Record<string, number>;
+//#endregion
+//#region src/countLines.d.ts
+/**
+ * Counts the number of lines in a string.
+ *
+ * @remarks
+ * - Handles Unix (`\n`), Windows (`\r\n`), and old Mac (`\r`) line endings.
+ *
+ * @returns Number of lines in the string.
+ *
+ * @example
+ * ```ts
+ * countLines("a\nb\nc");     // 3
+ * countLines("a\r\nb\r\nc"); // 3
+ * countLines("hello");       // 1
+ * ```
+ */
+declare function countLines(/** The input string. */
+str: string): number;
+//#endregion
+//#region src/countSubstring.d.ts
+/**
+ * Counts how many times a substring occurs within a string.
+ *
+ * @remarks
+ * - Overlapping substrings are not double-counted.
+ * - Returns `0` if the substring is not found.
+ *
+ * @returns Number of times `sub` occurs in `str`.
+ *
+ * @example
+ * ```ts
+ * countSubstring("lololol", "lo"); // 3
+ * countSubstring("aaaaa", "a");    // 5
+ * countSubstring("hello", "z");    // 0
+ * ```
+ */
+declare function countSubstring(/** The input string. */
+str: string, /** The substring to count. */
+sub: string): number;
+//#endregion
+//#region src/countWords.d.ts
+/**
+ * Counts the number of words in a string.
+ *
+ * @returns Number of words in the string.
+ *
+ * @example
+ * ```ts
+ * countWords("js utils kit");         // 3
+ * countWords("   js   utils   kit");  // 3
+ * countWords("");                     // 0
+ * ```
+ */
+declare function countWords(/** The input string */
+str: string): number;
+//#endregion
+//#region src/longestWord.d.ts
+/**
+ * Finds the longest word(s) in a string.
+ *
+ * @remarks
+ * - If only one longest word exists, returns it as a string.
+ * - If multiple longest words have the same length, returns them as an array.
+ * - Returns an empty string if there are no words.
+ *
+ * @returns The longest word as a string, or an array of tied words.
+ *
+ * @example
+ * ```ts
+ * longestWord("js utils kit");              // "utils"
+ * longestWord("short   longerword   mid"); // "longerword"
+ * longestWord("hello");                    // "hello"
+ * longestWord("");                         // ""
+ * ```
+ */
+declare function longestWord(/** The input string. */
+str: string): string | string[];
+//#endregion
+//#region src/longestWordLength.d.ts
+/**
+ * Finds the length of the longest word in a string.
+ *
+ * @remarks
+ * - Words are split by whitespace (`/\s+/`).
+ * - Symbols (punctuation, special chars) are removed using {@link stripSymbols}.
+ * - Returns `0` if the string is empty or contains no words.
+ *
+ * @returns Length of the longest word.
+ *
+ * @example
+ * ```ts
+ * longestWordLength("js utils kit");              // 5
+ * longestWordLength("short   longerword   mid"); // 10
+ * longestWordLength("hello");                    // 5
+ * longestWordLength("");                         // 0
+ * ```
+ */
+declare function longestWordLength(/** The input string. */
+str: string): number;
+//#endregion
+//#region src/padLeft.d.ts
+/**
+ * Pads a string on the left with a specified character until it reaches the desired length.
+ *
+ * @returns The padded string, or the original string if its length is already greater than or equal to the target length.
+ *
+ * @example
+ * ```ts
+ * console.log(padLeft("hello", 8)); // "   hello"
+ * console.log(padLeft("hi", 5, "*")); // "***hi"
+ * console.log(padLeft("hello", 3)); // "hello"
+ * console.log(padLeft("", 3, "0")); // "000"
+ * ```
+ */
+declare function padLeft(/** The string to pad */
+str: string, /** The target length of the padded string */
+length: number,
+/**
+ * The character to use for padding (defaults to a space)
+ *
+ * @default ' '
+ */
+char?: string): string;
+//#endregion
+//#region src/padRight.d.ts
+/**
+ * Pads a string on the right with a specified character until it reaches the desired length.
+ *
+ * @returns The padded string, or the original string if its length is already greater than or equal to the target length.
+ *
+ * @example
+ * ```ts
+ * console.log(padRight("hello", 8)); // "hello   "
+ * console.log(padRight("hi", 5, "*")); // "hi***"
+ * console.log(padRight("hello", 3)); // "hello"
+ * console.log(padRight("", 3, "0")); // "000"
+ * ```
+ */
+declare function padRight(/** The string to pad */
+str: string, /** The target length of the padded string */
+length: number,
+/**
+ * The character to use for padding (defaults to a space)
+ *
+ * @default ' '
+ */
+char?: string): string;
+//#endregion
+//#region src/repeatString.d.ts
+/**
+ * Repeats a string a specified number of times.
+ *
+ * @returns The string repeated the specified number of times.
+ *
+ * @example
+ * ```ts
+ * console.log(repeatString("hi", 3)); // "hihihi"
+ * console.log(repeatString("a", 2)); // "aa"
+ * console.log(repeatString("test", 0)); // ""
+ * console.log(repeatString("", 5)); // ""
+ * ```
+ */
+declare function repeatString(/** The string to repeat */
+str: string, /** The number of times to repeat the string (must be non-negative) */
+count: number): string;
+//#endregion
+//#region src/shortestWord.d.ts
+/**
+ * Finds the shortest word(s) in a string.
+ *
+ * @remarks
+ * - If only one shortest word exists, returns it as a string.
+ * - If multiple shortest words have the same length, returns them as an array.
+ * - Returns an empty string if there are no words.
+ *
+ * @returns The shortest word as a string, or an array of tied words.
+ *
+ * @example
+ * ```ts
+ * shortestWord("js utils kit"); // "js"
+ * shortestWord("one three five"); // "one"
+ * shortestWord("a ab abc abcd"); // "a"
+ * shortestWord(""); // ""
+ * ```
+ */
+declare function shortestWord(/** The input string. */
+str: string): string | string[];
+//#endregion
+//#region src/shortestWordLength.d.ts
+/**
+ * Finds the length of the shortest word in a string.
+ *
+ * @remarks
+ * - Words are split by whitespace (`/\s+/`).
+ * - Symbols (punctuation, special chars) are removed using {@link stripSymbols}.
+ * - Returns `0` if the string is empty or contains no words.
+ *
+ * @returns Length of the shortest word.
+ *
+ * @example
+ * ```ts
+ * shortestWordLength("js utils kit"); // 2
+ * shortestWordLength("one three five"); // 3
+ * shortestWordLength(""); // 0
+ * ```
+ */
+declare function shortestWordLength(/** The input string. */
+str: string): number;
+//#endregion
+//#region src/splitString.d.ts
+/**
+ * Splits a string into an array of substrings using a given delimiter.
+ *
+ * @remarks
+ * - Defaults to splitting by whitespace using `/\s+/`.
+ * - Does not trim leading/trailing spaces unless explicitly passed.
+ * - Leading/trailing delimiters may produce empty strings.
+ * - With `/\s+/` specifically, consecutive whitespace is collapsed (no interior empty tokens).
+ *
+ * @returns An array of substrings.
+ *
+ * @example
+ * ```ts
+ * splitString("a b  c");      // ["a", "b", "c"]
+ * splitString("a,b,c", ",");  // ["a", "b", "c"]
+ * splitString("a1b2c3", /\d/); // ["a", "b", "c", ""]
+ * ```
+ */
+declare function splitString(/** The input string to split. */
+str: string,
+/**
+ * The delimiter (string or RegExp)
+ *
+ * @default whitespace  `/\s+/`
+ */
+val?: string | RegExp): string[];
+//#endregion
+//#region src/stripSymbols.d.ts
+/**
+ * Removes or replaces common symbol characters from a string.
+ *
+ * @remarks
+ * - Strips symbols like `- _ @ ! $ % ^ & # * ( ) + = , . ; : ' " < > ? / \ | [ ] { }`.
+ * - Keeps letters, numbers, and spaces intact.
+ * - By default, removes symbols (replaces with `""`).
+ *
+ * @returns A new string with symbols removed or replaced.
+ *
+ * @example
+ * ```ts
+ * stripSymbols("hello-world!");              // "helloworld"
+ * stripSymbols("hello-world!", " ");         // "hello world "
+ * stripSymbols("user_name@test", "_");       // "user_nametest"
+ * stripSymbols("symbols-only!!!", "*");      // "symbols-only***"
+ * ```
+ */
+declare function stripSymbols(/** The input string */
+str: string,
+/**
+ * Optional replacement string for removed symbols.
+ *
+ * @default ""
+ */
+replacement?: string): string;
+//#endregion
+//#region src/trim.d.ts
+/**
+ * Trims whitespace from a string with methods for leading and trailing and normalizing whitespace.
+ *
+ * @param str - The string to trim.
+ *
+ * @returns The string with leading and trailing whitespace removed.
+ *
+ * @remarks
+ * - The main callable form behaves like {@link String.prototype.trim}, removing whitespace from both ends.
+ * - `.start` removes only leading whitespace (like {@link String.prototype.trimStart}).
+ * - `.end` removes only trailing whitespace (like {@link String.prototype.trimEnd}).
+ * - `.normalizeWhitespace` trims the string and replaces any sequence of whitespace characters with a single space.
+ *
+ * @default 'trims both sides'
+ *
+ * @example
+ * ```ts
+ * // Trim both sides
+ * console.log(trim("  hello  ")); // "hello"
+ * console.log(trim("")); // ""
+ * console.log(trim("hello")); // "hello"
+ *
+ * // Trim leading whitespace
+ * console.log(trim.start("  hello  ")); // "hello  "
+ * console.log(trim.start("")); // ""
+ * console.log(trim.start("hello")); // "hello"
+ *
+ * // Trim trailing whitespace
+ * console.log(trim.end("  hello  ")); // "  hello"
+ * console.log(trim.end("")); // ""
+ * console.log(trim.end("hello")); // "hello"
+ *
+ * // Normalize whitespace
+ * console.log(trim.normalizeWhitespace("  hello   world  ")); // "hello world"
+ * console.log(trim.normalizeWhitespace("hello\t  world")); // "hello world"
+ * console.log(trim.normalizeWhitespace("")); // ""
+ * ```
+ */
+declare const trim: Trim;
+//#endregion
+//#region src/truncate.d.ts
+/**
+ * Truncates a string to a specified length, appending a suffix if the string is too long.
+ *
+ * @returns The truncated string with the suffix if the original string exceeds the length, otherwise the original string.
+ *
+ * @example
+ * ```ts
+ * console.log(truncate("hello world", 8)); // "hello..."
+ * console.log(truncate("hi", 5)); // "hi"
+ * console.log(truncate("hello", 5, "...")); // "hello"
+ * console.log(truncate("", 3)); // ""
+ * ```
+ */
+declare function truncate(/** The string to truncate */
+str: string, /** The maximum length of the resulting string */
+length: number,
+/**
+ * The suffix to append if truncation occurs
+ *
+ * @default "..."
+ */
+suffix?: string): string;
+//#endregion
+//#region src/uniqueChars.d.ts
+/**
+ * Returns an array of unique characters from a string.
+ *
+ * @remarks
+ * - Preserves order of first appearance.
+ *
+ * @returns Array of unique characters.
+ *
+ * @example
+ * ```ts
+ * uniqueChars("banana"); // ["b", "a", "n"]
+ * uniqueChars("");       // []
+ * ```
+ */
+declare function uniqueChars(/** The input string. */
+str: string): string[];
+//#endregion
+export { capitalize, countChars, countFrequencies, countLines, countSubstring, countWords, longestWord, longestWordLength, padLeft, padRight, repeatString, shortestWord, shortestWordLength, splitString, stripSymbols, trim, truncate, uniqueChars };

package/dist/index.d.mts

@@ -0,0 +1,413 @@
+import { Trim } from "@js-utils-kit/types";
+export * from "@js-utils-kit/types";
+
+//#region src/capitalize.d.ts
+
+/**
+ * Capitalizes the first character of a string using a regular expression.
+ *
+ * @returns The input string with its first character capitalized, or the original string if empty or not a string.
+ *
+ * @example
+ * ```ts
+ * capitalize("hello"); // "Hello"
+ * capitalize("world"); // "World"
+ * capitalize(""); // ""
+ * capitalize("a"); // "A"
+ * ```
+ */
+declare function capitalize(/** The string to capitalize */
+value: string): string;
+//#endregion
+//#region src/countChars.d.ts
+/**
+ * Counts characters in a string.
+ *
+ * @remarks
+ * - If `char` is provided, only that character’s occurrences are counted.
+ * - If `char` is omitted, the function counts the number of substrings returned by {@link splitString} (similar to a word count).
+ *
+ * @returns Number of characters or character occurrences.
+ *
+ * @example
+ * ```ts
+ * countChars("banana");       // 6
+ * countChars("banana", "a");  // 3
+ * countChars("banana", "n");  // 2
+ * ```
+ */
+declare function countChars(/** The input string. */
+str: string, /** Optional character to count. */
+char?: string): number;
+//#endregion
+//#region src/countFrequencies.d.ts
+/**
+ * Builds a frequency map of characters in a string.
+ *
+ * @remarks
+ * - Returns an object where keys are characters and values are counts.
+ * - Case-sensitive by default.
+ *
+ * @returns A mapping of each character to its frequency.
+ *
+ * @example
+ * ```ts
+ * countFrequencies("banana");
+ * // { b: 1, a: 3, n: 2 }
+ *
+ * countFrequencies("");
+ * // {}
+ * ```
+ */
+declare function countFrequencies(/** The input string. */
+str: string): Record<string, number>;
+//#endregion
+//#region src/countLines.d.ts
+/**
+ * Counts the number of lines in a string.
+ *
+ * @remarks
+ * - Handles Unix (`\n`), Windows (`\r\n`), and old Mac (`\r`) line endings.
+ *
+ * @returns Number of lines in the string.
+ *
+ * @example
+ * ```ts
+ * countLines("a\nb\nc");     // 3
+ * countLines("a\r\nb\r\nc"); // 3
+ * countLines("hello");       // 1
+ * ```
+ */
+declare function countLines(/** The input string. */
+str: string): number;
+//#endregion
+//#region src/countSubstring.d.ts
+/**
+ * Counts how many times a substring occurs within a string.
+ *
+ * @remarks
+ * - Overlapping substrings are not double-counted.
+ * - Returns `0` if the substring is not found.
+ *
+ * @returns Number of times `sub` occurs in `str`.
+ *
+ * @example
+ * ```ts
+ * countSubstring("lololol", "lo"); // 3
+ * countSubstring("aaaaa", "a");    // 5
+ * countSubstring("hello", "z");    // 0
+ * ```
+ */
+declare function countSubstring(/** The input string. */
+str: string, /** The substring to count. */
+sub: string): number;
+//#endregion
+//#region src/countWords.d.ts
+/**
+ * Counts the number of words in a string.
+ *
+ * @returns Number of words in the string.
+ *
+ * @example
+ * ```ts
+ * countWords("js utils kit");         // 3
+ * countWords("   js   utils   kit");  // 3
+ * countWords("");                     // 0
+ * ```
+ */
+declare function countWords(/** The input string */
+str: string): number;
+//#endregion
+//#region src/longestWord.d.ts
+/**
+ * Finds the longest word(s) in a string.
+ *
+ * @remarks
+ * - If only one longest word exists, returns it as a string.
+ * - If multiple longest words have the same length, returns them as an array.
+ * - Returns an empty string if there are no words.
+ *
+ * @returns The longest word as a string, or an array of tied words.
+ *
+ * @example
+ * ```ts
+ * longestWord("js utils kit");              // "utils"
+ * longestWord("short   longerword   mid"); // "longerword"
+ * longestWord("hello");                    // "hello"
+ * longestWord("");                         // ""
+ * ```
+ */
+declare function longestWord(/** The input string. */
+str: string): string | string[];
+//#endregion
+//#region src/longestWordLength.d.ts
+/**
+ * Finds the length of the longest word in a string.
+ *
+ * @remarks
+ * - Words are split by whitespace (`/\s+/`).
+ * - Symbols (punctuation, special chars) are removed using {@link stripSymbols}.
+ * - Returns `0` if the string is empty or contains no words.
+ *
+ * @returns Length of the longest word.
+ *
+ * @example
+ * ```ts
+ * longestWordLength("js utils kit");              // 5
+ * longestWordLength("short   longerword   mid"); // 10
+ * longestWordLength("hello");                    // 5
+ * longestWordLength("");                         // 0
+ * ```
+ */
+declare function longestWordLength(/** The input string. */
+str: string): number;
+//#endregion
+//#region src/padLeft.d.ts
+/**
+ * Pads a string on the left with a specified character until it reaches the desired length.
+ *
+ * @returns The padded string, or the original string if its length is already greater than or equal to the target length.
+ *
+ * @example
+ * ```ts
+ * console.log(padLeft("hello", 8)); // "   hello"
+ * console.log(padLeft("hi", 5, "*")); // "***hi"
+ * console.log(padLeft("hello", 3)); // "hello"
+ * console.log(padLeft("", 3, "0")); // "000"
+ * ```
+ */
+declare function padLeft(/** The string to pad */
+str: string, /** The target length of the padded string */
+length: number,
+/**
+ * The character to use for padding (defaults to a space)
+ *
+ * @default ' '
+ */
+char?: string): string;
+//#endregion
+//#region src/padRight.d.ts
+/**
+ * Pads a string on the right with a specified character until it reaches the desired length.
+ *
+ * @returns The padded string, or the original string if its length is already greater than or equal to the target length.
+ *
+ * @example
+ * ```ts
+ * console.log(padRight("hello", 8)); // "hello   "
+ * console.log(padRight("hi", 5, "*")); // "hi***"
+ * console.log(padRight("hello", 3)); // "hello"
+ * console.log(padRight("", 3, "0")); // "000"
+ * ```
+ */
+declare function padRight(/** The string to pad */
+str: string, /** The target length of the padded string */
+length: number,
+/**
+ * The character to use for padding (defaults to a space)
+ *
+ * @default ' '
+ */
+char?: string): string;
+//#endregion
+//#region src/repeatString.d.ts
+/**
+ * Repeats a string a specified number of times.
+ *
+ * @returns The string repeated the specified number of times.
+ *
+ * @example
+ * ```ts
+ * console.log(repeatString("hi", 3)); // "hihihi"
+ * console.log(repeatString("a", 2)); // "aa"
+ * console.log(repeatString("test", 0)); // ""
+ * console.log(repeatString("", 5)); // ""
+ * ```
+ */
+declare function repeatString(/** The string to repeat */
+str: string, /** The number of times to repeat the string (must be non-negative) */
+count: number): string;
+//#endregion
+//#region src/shortestWord.d.ts
+/**
+ * Finds the shortest word(s) in a string.
+ *
+ * @remarks
+ * - If only one shortest word exists, returns it as a string.
+ * - If multiple shortest words have the same length, returns them as an array.
+ * - Returns an empty string if there are no words.
+ *
+ * @returns The shortest word as a string, or an array of tied words.
+ *
+ * @example
+ * ```ts
+ * shortestWord("js utils kit"); // "js"
+ * shortestWord("one three five"); // "one"
+ * shortestWord("a ab abc abcd"); // "a"
+ * shortestWord(""); // ""
+ * ```
+ */
+declare function shortestWord(/** The input string. */
+str: string): string | string[];
+//#endregion
+//#region src/shortestWordLength.d.ts
+/**
+ * Finds the length of the shortest word in a string.
+ *
+ * @remarks
+ * - Words are split by whitespace (`/\s+/`).
+ * - Symbols (punctuation, special chars) are removed using {@link stripSymbols}.
+ * - Returns `0` if the string is empty or contains no words.
+ *
+ * @returns Length of the shortest word.
+ *
+ * @example
+ * ```ts
+ * shortestWordLength("js utils kit"); // 2
+ * shortestWordLength("one three five"); // 3
+ * shortestWordLength(""); // 0
+ * ```
+ */
+declare function shortestWordLength(/** The input string. */
+str: string): number;
+//#endregion
+//#region src/splitString.d.ts
+/**
+ * Splits a string into an array of substrings using a given delimiter.
+ *
+ * @remarks
+ * - Defaults to splitting by whitespace using `/\s+/`.
+ * - Does not trim leading/trailing spaces unless explicitly passed.
+ * - Leading/trailing delimiters may produce empty strings.
+ * - With `/\s+/` specifically, consecutive whitespace is collapsed (no interior empty tokens).
+ *
+ * @returns An array of substrings.
+ *
+ * @example
+ * ```ts
+ * splitString("a b  c");      // ["a", "b", "c"]
+ * splitString("a,b,c", ",");  // ["a", "b", "c"]
+ * splitString("a1b2c3", /\d/); // ["a", "b", "c", ""]
+ * ```
+ */
+declare function splitString(/** The input string to split. */
+str: string,
+/**
+ * The delimiter (string or RegExp)
+ *
+ * @default whitespace  `/\s+/`
+ */
+val?: string | RegExp): string[];
+//#endregion
+//#region src/stripSymbols.d.ts
+/**
+ * Removes or replaces common symbol characters from a string.
+ *
+ * @remarks
+ * - Strips symbols like `- _ @ ! $ % ^ & # * ( ) + = , . ; : ' " < > ? / \ | [ ] { }`.
+ * - Keeps letters, numbers, and spaces intact.
+ * - By default, removes symbols (replaces with `""`).
+ *
+ * @returns A new string with symbols removed or replaced.
+ *
+ * @example
+ * ```ts
+ * stripSymbols("hello-world!");              // "helloworld"
+ * stripSymbols("hello-world!", " ");         // "hello world "
+ * stripSymbols("user_name@test", "_");       // "user_nametest"
+ * stripSymbols("symbols-only!!!", "*");      // "symbols-only***"
+ * ```
+ */
+declare function stripSymbols(/** The input string */
+str: string,
+/**
+ * Optional replacement string for removed symbols.
+ *
+ * @default ""
+ */
+replacement?: string): string;
+//#endregion
+//#region src/trim.d.ts
+/**
+ * Trims whitespace from a string with methods for leading and trailing and normalizing whitespace.
+ *
+ * @param str - The string to trim.
+ *
+ * @returns The string with leading and trailing whitespace removed.
+ *
+ * @remarks
+ * - The main callable form behaves like {@link String.prototype.trim}, removing whitespace from both ends.
+ * - `.start` removes only leading whitespace (like {@link String.prototype.trimStart}).
+ * - `.end` removes only trailing whitespace (like {@link String.prototype.trimEnd}).
+ * - `.normalizeWhitespace` trims the string and replaces any sequence of whitespace characters with a single space.
+ *
+ * @default 'trims both sides'
+ *
+ * @example
+ * ```ts
+ * // Trim both sides
+ * console.log(trim("  hello  ")); // "hello"
+ * console.log(trim("")); // ""
+ * console.log(trim("hello")); // "hello"
+ *
+ * // Trim leading whitespace
+ * console.log(trim.start("  hello  ")); // "hello  "
+ * console.log(trim.start("")); // ""
+ * console.log(trim.start("hello")); // "hello"
+ *
+ * // Trim trailing whitespace
+ * console.log(trim.end("  hello  ")); // "  hello"
+ * console.log(trim.end("")); // ""
+ * console.log(trim.end("hello")); // "hello"
+ *
+ * // Normalize whitespace
+ * console.log(trim.normalizeWhitespace("  hello   world  ")); // "hello world"
+ * console.log(trim.normalizeWhitespace("hello\t  world")); // "hello world"
+ * console.log(trim.normalizeWhitespace("")); // ""
+ * ```
+ */
+declare const trim: Trim;
+//#endregion
+//#region src/truncate.d.ts
+/**
+ * Truncates a string to a specified length, appending a suffix if the string is too long.
+ *
+ * @returns The truncated string with the suffix if the original string exceeds the length, otherwise the original string.
+ *
+ * @example
+ * ```ts
+ * console.log(truncate("hello world", 8)); // "hello..."
+ * console.log(truncate("hi", 5)); // "hi"
+ * console.log(truncate("hello", 5, "...")); // "hello"
+ * console.log(truncate("", 3)); // ""
+ * ```
+ */
+declare function truncate(/** The string to truncate */
+str: string, /** The maximum length of the resulting string */
+length: number,
+/**
+ * The suffix to append if truncation occurs
+ *
+ * @default "..."
+ */
+suffix?: string): string;
+//#endregion
+//#region src/uniqueChars.d.ts
+/**
+ * Returns an array of unique characters from a string.
+ *
+ * @remarks
+ * - Preserves order of first appearance.
+ *
+ * @returns Array of unique characters.
+ *
+ * @example
+ * ```ts
+ * uniqueChars("banana"); // ["b", "a", "n"]
+ * uniqueChars("");       // []
+ * ```
+ */
+declare function uniqueChars(/** The input string. */
+str: string): string[];
+//#endregion
+export { capitalize, countChars, countFrequencies, countLines, countSubstring, countWords, longestWord, longestWordLength, padLeft, padRight, repeatString, shortestWord, shortestWordLength, splitString, stripSymbols, trim, truncate, uniqueChars };

package/dist/index.mjs

@@ -0,0 +1 @@
+export*from"@js-utils-kit/types";function e(e){return e.replace(/^\w/,e=>e.toUpperCase())}function t(e,t=/\s+/){return e.split(t)}function n(e,n){return n?[...e].filter(e=>e===n).length:t(e).length}function r(e){return[...e].reduce((e,t)=>(e[t]=(e[t]||0)+1,e),{})}function i(e){return e?t(e,/\r\n|\r|\n/).length:0}function a(e,n){return n.length===0?0:t(e,n).length-1}function o(e){return t(e.trim()).length}function s(e,t=``){return e.replace(/[^\p{L}\p{N}\s]/gu,t)}function c(e){let n=t(e.trim()).map(e=>s(e)).filter(Boolean);if(n.length===0)return``;let r=Math.max(...n.map(e=>e.length)),i=n.filter(e=>e.length===r),a=[...new Set(i)];return a.length===1?a[0]:a}function l(e){let n=t(e).map(e=>s(e)).filter(Boolean);return n.length===0?0:n.reduce((e,t)=>Math.max(e,t.length),0)}function u(e,t,n=` `){return e.padStart(t,n)}function d(e,t,n=` `){return e.padEnd(t,n)}function f(e,t){return e.repeat(t)}function p(e){let n=t(e.trim()).map(e=>s(e)).filter(Boolean);if(n.length===0)return``;let r=Math.min(...n.map(e=>e.length)),i=n.filter(e=>e.length===r),a=[...new Set(i)];return a.length===1?a[0]:a}function m(e){let n=t(e.trim()).map(e=>s(e)).filter(Boolean);return n.length===0?0:n.reduce((e,t)=>Math.min(e,t.length),1/0)}const h=Object.assign(e=>e.trim(),{start:e=>e.trimStart(),end:e=>e.trimEnd(),normalizeWhitespace:e=>e.trim().replace(/\s+/g,` `)});function g(e,t,n=`...`){return t<=0?``:e.length<=t?e:n.length>=t?n.slice(0,t):e.trim().slice(0,t)+n}function _(e){return[...new Set(e)]}export{e as capitalize,n as countChars,r as countFrequencies,i as countLines,a as countSubstring,o as countWords,c as longestWord,l as longestWordLength,u as padLeft,d as padRight,f as repeatString,p as shortestWord,m as shortestWordLength,t as splitString,s as stripSymbols,h as trim,g as truncate,_ as uniqueChars};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@js-utils-kit/string",
+  "version": "1.0.0",
+  "description": "String utilities",
+  "license": "MIT",
+  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/teneplaysofficial/js-utils-kit",
+    "directory": "packages/string"
+  },
+  "bugs": {
+    "url": "https://github.com/teneplaysofficial/js-utils-kit/issues"
+  },
+  "author": {
+    "name": "Sriman",
+    "email": "136729116+TenEplaysOfficial@users.noreply.github.com",
+    "url": "https://tene.vercel.app"
+  },
+  "keywords": [
+    "string",
+    "string-utils",
+    "stringify",
+    "text",
+    "case",
+    "trim",
+    "format",
+    "sanitize",
+    "camelcase",
+    "typescript",
+    "utilities"
+  ],
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "dependencies": {
+    "@js-utils-kit/types": "1.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "test": "vitest run"
+  }
+}