toolbox-x 1.0.0

package/dist/case-BWIt8Ash.mjs

@@ -0,0 +1,449 @@
+/**
+ * Copyright 2026 - present Nazmul Hassan
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { a as isNonEmptyString } from "./primitives-KsFUp3kQ.mjs";
+import { t as LOWERCASE } from "./constants-2gAw23_7.mjs";
+
+//#region src/string/case.ts
+/** Lowercase words set for fast lookup */
+const smallSet = /* @__PURE__ */ new Set(LOWERCASE);
+/**
+* * Converts a string to a specified case format with advanced handling for word boundaries, punctuation, acronyms, and Unicode characters.
+*
+* @remarks
+* - This function is Unicode-aware, treats non-alphanumeric characters (spaces, underscores, dots, slashes, etc.) as word boundaries, and optionally preserves internal acronyms.
+* - `Title Case` formatting respects small words such as prepositions, articles, conjunctions, and auxiliary verbs (defined in `LOWERCASE`) — these are not capitalized unless they appear at the start or end of the string.
+* - Leading and trailing punctuation (non-letter/number characters) is preserved in the result.
+*
+* @param value - The input string to convert. Can contain letters, numbers, punctuation,
+*   spaces, underscores, dashes, etc.
+* @param format - The target case format:
+*   - `'camelCase'` → camelCase (e.g., `myVariableName`)
+*   - `'PascalCase'` → PascalCase (e.g., `MyVariableName`)
+*   - `'snake_case'` → snake_case (e.g., `my_variable_name`)
+*   - `'kebab-case'` → kebab-case (e.g., `my-variable-name`)
+*   - `'Title Case'` → Title Case (e.g., `My Variable Name`)
+*   - `'Sentence case'` → Sentence case (e.g., `My variable name`)
+*   - `'lowercase'` → all lowercase [ It is recommended to use built-in string method `string.toLowerCase()` ]
+*   - `'UPPERCASE'` → all uppercase [ It is recommended to use built-in string method `string.toUpperCase()` ]
+* @param options - Optional configuration options for more control.
+*
+* @returns The converted string, with leading/trailing punctuation preserved.
+*
+* @example
+* // Basic usage
+* convertStringCase('my-example_string', 'camelCase');
+* // Returns: 'myExampleString'
+*
+* convertStringCase('my-example_string', 'snake_case');
+* // Returns: 'my_example_string'
+*
+* convertStringCase('my-example_string', 'kebab-case');
+* // Returns: 'my-example-string'
+*
+* convertStringCase('my example string', 'Title Case');
+* // Returns: 'My Example String'
+*
+* convertStringCase('my example string', 'Sentence case');
+* // Returns: 'My example string'
+*
+* convertStringCase('My example String', 'lowercase');
+* // Returns: 'my example string'
+*
+* convertStringCase('my example string', 'UPPERCASE');
+* // Returns: 'MY EXAMPLE STRING'
+*
+* @example
+* // Preserve acronyms
+* convertStringCase('get API response', 'camelCase', { preserveAcronyms: true });
+* // Returns: 'getAPIResponse'
+*
+* convertStringCase('get API response', 'PascalCase', { preserveAcronyms: true });
+* // Returns: 'GetAPIResponse'
+*
+* convertStringCase('the API of things', 'Title Case', { preserveAcronyms: true });
+* // Returns: 'The API of Things'
+*
+* @example
+* // Leading/trailing punctuation is preserved
+* convertStringCase('++hello_world++', 'PascalCase');
+* // Returns: '++HelloWorld++'
+*
+* @example
+* // Dashes are preserved in Title Case
+* convertStringCase('xml-http_request', 'Title Case');
+* // Returns: 'Xml-http Request'
+*
+* @example
+* // Empty string returns empty
+* convertStringCase('', 'camelCase');
+* // Returns: ''
+*
+* @example
+* // Single token is capitalized properly
+* convertStringCase('api', 'PascalCase');
+* // Returns: 'Api'
+*/
+function convertStringCase(value, format, options) {
+	if (!isNonEmptyString(value)) return "";
+	const { preserveAcronyms = false } = options ?? {};
+	const LEADING_PUNCTUATION = /^[^\p{L}\p{N}\s]+/u;
+	const TRAILING_PUNCTUATION = /[^\p{L}\p{N}\s]+$/u;
+	const SEPARATOR = format === "Title Case" ? /[^\p{L}\p{N}-]+/gu : /[^\p{L}\p{N}]+/gu;
+	const CAMEL_BOUNDARY = /(?<=[\p{Ll}\p{N}])(?=\p{Lu})|(?<=[\p{Lu}])(?=\p{Lu}[\p{Ll}])/u;
+	const LETTER_NUMBER_BOUNDARY = /(?<=[\p{L}])(?=\p{N})|(?<=[\p{N}])(?=\p{L})/u;
+	const start = value.match(LEADING_PUNCTUATION)?.[0] ?? "";
+	const end = value.match(TRAILING_PUNCTUATION)?.[0] ?? "";
+	const core = value.replace(/^[^\p{L}\p{N}\s]+|[^\p{L}\p{N}\s]+$/gu, "").trim();
+	const lowerCase = (s) => s.toLowerCase();
+	const isAcronym = (s) => s.length >= 2 && /^[\p{Lu}]+$/u.test(s);
+	const capitalize = (s) => s.length === 0 ? "" : _capitalize(s);
+	let tokens = core.length > 0 ? core.split(SEPARATOR).filter(Boolean) : [];
+	if (tokens.length <= 1 && core.length > 0) if (CAMEL_BOUNDARY.test(core)) tokens = core.split(CAMEL_BOUNDARY).filter(Boolean);
+	else if (LETTER_NUMBER_BOUNDARY.test(core)) tokens = core.split(LETTER_NUMBER_BOUNDARY).filter(Boolean);
+	else tokens = [core];
+	if (tokens.length === 0) return start.concat(end);
+	switch (format) {
+		case "camelCase": {
+			const middle = tokens.slice(1).map((token) => {
+				if (preserveAcronyms && isAcronym(token)) return token;
+				return capitalize(token);
+			}).join("");
+			return start.concat(lowerCase(tokens[0]).concat(middle), end);
+		}
+		case "PascalCase": {
+			const body = tokens.map((token) => {
+				if (preserveAcronyms && isAcronym(token)) return token;
+				return capitalize(token);
+			}).join("");
+			return start.concat(body, end);
+		}
+		case "snake_case": {
+			const body = tokens.map((token) => lowerCase(token)).join("_");
+			return start.concat(body, end);
+		}
+		case "kebab-case": {
+			const body = tokens.map((token) => lowerCase(token)).join("-");
+			return start.concat(body, end);
+		}
+		case "Title Case": {
+			const title = tokens.map((token, idx, self) => {
+				const tokenLower = token.toLowerCase();
+				if (idx !== 0 && idx !== self.length - 1 && smallSet.has(tokenLower)) return tokenLower;
+				if (preserveAcronyms && token.includes("-")) return token.split("-").map((sub) => isAcronym(sub) ? sub : capitalize(sub)).join("-");
+				if (preserveAcronyms && isAcronym(token)) return token.split("-");
+				return capitalize(token);
+			}).join(" ");
+			return start.concat(title, end);
+		}
+		case "Sentence case": {
+			const word = tokens.map((token, idx) => {
+				if (preserveAcronyms && token.includes("-")) return token.split("-").map((sub) => isAcronym(sub) ? sub : idx === 0 ? capitalize(sub) : sub.toLowerCase()).join("-");
+				if (preserveAcronyms && isAcronym(token)) return token.split("-");
+				return idx === 0 ? capitalize(token) : token.toLowerCase();
+			}).join(" ");
+			return start.concat(word, end);
+		}
+		case "lowercase": return start.concat(core.toLowerCase(), end);
+		case "UPPERCASE": return start.concat(core.toUpperCase(), end);
+		default: return start.concat(core, end);
+	}
+}
+/**
+* * Utility to convert the first letter of any string to uppercase and the rest lowercase (unless specified).
+* * Handles surrounding symbols like quotes or parentheses.
+*
+* @param string String to be capitalized.
+* @param options Options to customize the capitalization.
+* @returns Capitalized string or fully uppercased string depending on `capitalizeAll` option.
+*/
+function capitalizeString(string, options) {
+	if (!isNonEmptyString(string)) return "";
+	const trimmedString = string.trim();
+	if (!trimmedString) return "";
+	const { capitalizeAll = false, capitalizeEachFirst = false, lowerCaseRest = true } = options || {};
+	if (capitalizeAll) return trimmedString.toUpperCase();
+	if (capitalizeEachFirst) return trimmedString?.split(/\s+/)?.map((word) => capitalizeString(word, { lowerCaseRest }))?.join(" ");
+	const matchArray = trimmedString.match(/^(\W*)(\w)(.*)$/);
+	if (matchArray && matchArray?.length === 4) {
+		const [_, leadingSymbols, firstLetter, rest] = matchArray;
+		return leadingSymbols.concat(firstLetter.toUpperCase()).concat(lowerCaseRest ? rest.toLowerCase() : rest);
+	}
+	return trimmedString.charAt(0).toUpperCase().concat(lowerCaseRest ? trimmedString.slice(1).toLowerCase() : trimmedString.slice(1));
+}
+/** Cache to store regex for delimiters */
+const REGEX_CACHE = /* @__PURE__ */ new Map();
+/** Get delimiter regex from cache if already built the regex in previous call */
+function _getDelimiterRegex(delims) {
+	const key = delims.sort().join("");
+	if (!REGEX_CACHE.has(key)) REGEX_CACHE.set(key, new RegExp(`[-_./${delims.join("")}]`, "g"));
+	return REGEX_CACHE.get(key);
+}
+/** Normalizes delimiters + splits the string */
+function _normalizeDelimiters(str, delims) {
+	const delRegExp = _getDelimiterRegex(delims);
+	return str.replace(/(\p{Ll}?\d+|(?<=\p{Lu}))(\p{Lu})/gu, "$1 $2").replace(delRegExp, " ").replace(/\s+/g, " ").trim().split(" ").filter(Boolean);
+}
+/** Capitalize a string (first letter capital, rest lowercase) */
+function _capitalize(str) {
+	return str.charAt(0).toUpperCase() + str.slice(1).toLowerCase();
+}
+/**
+* * Converts a string into `camelCase`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toCamelCase("hello world")            // "helloWorld"
+* toCamelCase("my-awesome_string")      // "myAwesomeString"
+* toCamelCase("value*with+custom", "*+") // "valueWithCustom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `camelCase` formatted string.
+*/
+function toCamelCase(str, ...del) {
+	if (!isNonEmptyString(str)) return "";
+	const parts = _normalizeDelimiters(str, del);
+	return parts[0].toLowerCase() + parts.slice(1).map(_capitalize).join("");
+}
+/**
+* * Converts a string into `PascalCase`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toPascalCase("hello world")            // "HelloWorld"
+* toPascalCase("my-awesome_string")      // "MyAwesomeString"
+* toPascalCase("value*with+custom", "*+") // "ValueWithCustom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `PascalCase` formatted string.
+*/
+function toPascalCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map(_capitalize).join("") : "";
+}
+/**
+* * Converts a string into `snake_case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toSnakeCase("hello world")            // "hello_world"
+* toSnakeCase("my-awesome_string")      // "my_awesome_string"
+* toSnakeCase("value*with+custom", "*+") // "value_with_custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `snake_case` formatted string.
+*/
+function toSnakeCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map((w) => w.toLowerCase()).join("_") : "";
+}
+/**
+* * Converts a string into `kebab-case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toKebabCase("hello world")            // "hello-world"
+* toKebabCase("my-awesome_string")      // "my-awesome-string"
+* toKebabCase("value*with+custom", "*+") // "value-with-custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `kebab-case` formatted string.
+*/
+function toKebabCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map((w) => w.toLowerCase()).join("-") : "";
+}
+/**
+* * Converts a string into `Train-Case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toTrainCase("hello world")            // "Hello-World"
+* toTrainCase("my-awesome_string")      // "My-Awesome-String"
+* toTrainCase("value*with+custom", "*+") // "Value-With-Custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `Train-Case` formatted string.
+*/
+function toTrainCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map(_capitalize).join("-") : "";
+}
+/**
+* * Converts a string into `dot.case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toDotCase("hello world")            // "hello.world"
+* toDotCase("my-awesome_string")      // "my.awesome.string"
+* toDotCase("value*with+custom", "*+") // "value.with.custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `dot.case` formatted string.
+*/
+function toDotCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).join(".") : "";
+}
+/**
+* * Converts a string into `path/case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toPathCase("hello world")            // "hello/world"
+* toPathCase("my-awesome_string")      // "my/awesome/string"
+* toPathCase("value*with+custom", "*+") // "value/with/custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `path/case` formatted string.
+*/
+function toPathCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map((w) => w.toLowerCase()).join("/") : "";
+}
+/**
+* * Converts a string into `CONSTANT_CASE`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toConstantCase("hello world")            // "HELLO_WORLD"
+* toConstantCase("my-awesome_string")      // "MY_AWESOME_STRING"
+* toConstantCase("value*with+custom", "*+") // "VALUE_WITH_CUSTOM"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `CONSTANT_CASE` formatted string.
+*/
+function toConstantCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map((w) => w.toUpperCase()).join("_") : "";
+}
+/**
+* * Converts a string into `Pascal_Snake_Case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toPascalSnakeCase("hello world")            // "Hello_World"
+* toPascalSnakeCase("my-awesome_string")      // "My_Awesome_String"
+* toPascalSnakeCase("value*with+custom", "*+") // "Value_With_Custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `Pascal_Snake_Case` formatted string.
+*/
+function toPascalSnakeCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map(_capitalize).join("_") : "";
+}
+/**
+* * Converts a string into `Title Case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toTitleCase("hello world")            // "Hello World"
+* toTitleCase("my-awesome_string")      // "My Awesome String"
+* toTitleCase("value*with+custom", "*+") // "Value with Custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `Title Case` formatted string.
+*/
+function toTitleCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map((w, i) => i !== 0 && smallSet.has(w) ? w.toLowerCase() : _capitalize(w)).join(" ") : "";
+}
+/**
+* * Converts a string into `Sentence case`, using the optional custom delimiters in addition to the default delimiters.
+*
+* @remarks
+* - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
+* - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
+*   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
+* - Use it for short literal strings (`up to 45 characters`) for best performance.
+* - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
+* - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
+*
+* @example
+* toSentenceCase("hello world")            // "Hello world"
+* toSentenceCase("my-awesome_string")      // "My awesome string"
+* toSentenceCase("value*with+custom", "*+") // "Value with custom"
+*
+* @param str The input string to convert.
+* @param del Additional delimiter characters to recognize.
+* @returns The `Sentence case` formatted string.
+*/
+function toSentenceCase(str, ...del) {
+	return isNonEmptyString(str) ? _normalizeDelimiters(str, del).map((w, i) => i === 0 ? _capitalize(w) : w.toLowerCase()).join(" ") : "";
+}
+
+//#endregion
+export { toDotCase as a, toPascalSnakeCase as c, toSnakeCase as d, toTitleCase as f, toConstantCase as i, toPathCase as l, convertStringCase as n, toKebabCase as o, toTrainCase as p, toCamelCase as r, toPascalCase as s, capitalizeString as t, toSentenceCase as u };