@rzl-zone/utils-js 3.0.2-beta.2 → 3.1.1-beta.0

package/dist/string-XA-til3C.d.ts

@@ -0,0 +1,351 @@
+import{I as If}from'./if-CvT4R7Kh.js';import{I as IsNever}from'./never-BfayMBF9.js';
+/** -------------------------------------------------------
+ * * ***IfNot.***
+ * -------------------------------------------------------
+ *
+ * Conditional: returns the second argument if the first argument is `false`, otherwise returns the third argument.
+ * - Defaults: `IfTrue = true`, `IfFalse = false`.
+ *
+ * @template Condition - The boolean condition to check.
+ * @template IfTrue - The branch type if condition is `false`. (default: `true`)
+ * @template IfFalse - The branch type if condition is `true`. (default: `false`)
+ *
+ * ### Examples
+ * ```ts
+ * type A = IfNot<false, "valid">;
+ * // ➔ "valid"
+ * type B = IfNot<false, "valid", "invalid">;
+ * // ➔ "invalid"
+ * ```
+ */
+type IfNot<Condition,IfTrue=true,IfFalse=false>=If<Condition,IfFalse,IfTrue>;
+/** -------------------------------------------------------
+ * * ***WordSeparator.***
+ * -------------------------------------------------------
+ * A type-level utility that defines all valid ***word separators***.
+ * - Can be a space `" "`, a dash `"-"`, or an underscore `"_"`.
+ *
+ * @example
+ * ```ts
+ * type A = WordSeparator; // ➔ " " | "-" | "_"
+ * ```
+ */
+type WordSeparator=" "|"-"|"_";
+/** --------------------------------------------------
+ * * ***Whitespace.***
+ * --------------------------------------------------
+ * Represents common whitespace characters.
+ *
+ * ✅ Used as the default trimming characters in string utility types.
+ *
+ * @example
+ * type W = Whitespace;
+ * // ➔ " " | "\t" | "\r" | "\n"
+ */
+type Whitespace=" "|"\t"|"\r"|"\n";
+/** **Helper Internal.** */
+type SafeKeyTrimming<T>=Exclude<T,symbol>;
+/** --------------------------------------------------
+ * * ***TrimLeft.***
+ * --------------------------------------------------
+ * Recursively trims specified characters (default: **{@link Whitespace}**)
+ * from the **start (left)** of a string.
+ *
+ * @template Text - The string to trim.
+ * @template Chars - The characters to remove (default: `Whitespace`).
+ *
+ * @example
+ * type T1 = TrimLeft<"\n  hello", " " | "\n">;
+ * // ➔ "hello"
+ *
+ * type T2 = TrimLeft<"  world">;
+ * // ➔ "world"
+ *
+ * type T3 = TrimLeft<"  world ">;
+ * // ➔ "world "
+ */
+type TrimLeft<Text extends PropertyKey,Chars extends PropertyKey=Whitespace>=Text extends`${SafeKeyTrimming<Chars>}${infer Rest}`?TrimLeft<Rest,Chars>:Text;
+/** --------------------------------------------------
+ * * ***TrimRight.***
+ * --------------------------------------------------
+ * Recursively trims specified characters (default: **{@link Whitespace}**)
+ * from the **end (right)** of a string.
+ *
+ * @template Text - The string to trim.
+ * @template Chars - The characters to remove (default: `Whitespace`).
+ *
+ * @example
+ * type T1 = TrimRight<"hello  \t", " " | "\t">;
+ * // ➔ "hello"
+ *
+ * type T2 = TrimRight<"world  ">;
+ * // ➔ "world"
+ *
+ * type T2 = TrimRight<" world  ">;
+ * // ➔ " world"
+ */
+type TrimRight<Text extends PropertyKey,Chars extends PropertyKey=Whitespace>=Text extends`${infer Rest}${SafeKeyTrimming<Chars>}`?TrimRight<Rest,Chars>:Text;
+/** --------------------------------------------------
+ * * ***Trim.***
+ * --------------------------------------------------
+ * Trims specified characters (default: **{@link Whitespace}**)
+ * from **both the start and end** of a string.
+ *
+ * @template Text - The string to trim.
+ * @template Chars - The characters to remove (default: `Whitespace`).
+ *
+ * @example
+ * type T1 = Trim<"  hello  ", " ">;
+ * // ➔ "hello"
+ *
+ * type T2 = Trim<"\n  world \t">;
+ * // ➔ "world"
+ */
+type Trim<Text extends PropertyKey,Chars extends PropertyKey=Whitespace>=TrimRight<TrimLeft<Text,Chars>,Chars>;
+/** -------------------------------------------------------
+ * * ***TrimsLower***
+ * -------------------------------------------------------
+ * Trims leading & trailing whitespace from a string and
+ * converts it to **lowercase**.
+ *
+ * Utilizes **{@link Trim}** to remove whitespace and **{@link Lowercase}** to convert the string to lowercase.
+ *
+ * @template S - The input string to transform.
+ *
+ * @example
+ * ```ts
+ * type T1 = TrimsLower<"  HeLLo \n">;
+ * // ➔ "hello"
+ *
+ * type T2 = TrimsLower<"  WoRLD  ">;
+ * // ➔ "world"
+ * ```
+ */
+type TrimsLower<S extends string>=Lowercase<Trim<S>>;
+/** -------------------------------------------------------
+ * * ***TrimsUpper***
+ * -------------------------------------------------------
+ * Trims leading & trailing whitespace from a string and
+ * converts it to **uppercase**.
+ *
+ * Utilizes **{@link Trim}** to remove whitespace and **{@link Uppercase}** to convert the string to uppercase.
+ *
+ * @template S - The input string to transform.
+ *
+ * @example
+ * ```ts
+ * type T1 = TrimsUpper<"  HeLLo \n">;
+ * // ➔ "HELLO"
+ *
+ * type T2 = TrimsUpper<"  WoRLD  ">;
+ * // ➔ "WORLD"
+ * ```
+ */
+type TrimsUpper<S extends string>=Uppercase<Trim<S>>;
+/** -------------------------------------------------------
+ * * ***AnyString.***
+ * -------------------------------------------------------
+ *
+ * A utility type that represents **any string value** while
+ * preventing unwanted widening of string literals to `string`.
+ *
+ * 🔹 This is achieved by intersecting `string` with `{}`,
+ * ensuring that the type remains assignable to `string`
+ * but is treated as a unique type in generic constraints.
+ *
+ * 📌 Useful in scenarios where:
+ * - You want to accept **any string**, but still preserve
+ *   literal types in inference.
+ * - You need stricter typing than just `string`.
+ *
+ * @example
+ * ```ts
+ * declare function acceptsAnyString<T extends AnyString>(value: T): T;
+ *
+ * // Preserves literal
+ * const a = acceptsAnyString("hello");
+ * // ➔ "hello"
+ *
+ * // Also allows generic string
+ * const b = acceptsAnyString(String("world"));
+ * // ➔ string
+ * ```
+ */
+type AnyString={}& string;
+/** -------------------------------------------------------
+ * * ***EmptyString.***
+ * -------------------------------------------------------
+ * Returns the type `T` only if it is the empty string `""`.
+ * Optionally trims whitespace before checking.
+ *
+ * Behavior:
+ * - If `WithTrim` is `true` (default), trims `T` before checking.
+ * - If `T` is the general `string` type, returns `never`.
+ * - If `T` is empty (after optional trimming), returns `T` or `Trim<T>`.
+ *
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ *
+ * @example
+ * ```ts
+ * // Basic empty string
+ * type Case1 = EmptyString<"">;
+ * // ➔ ""
+ *
+ * // Non-empty string
+ * type Case2 = EmptyString<"abc">;
+ * // ➔ never
+ *
+ * // General string type
+ * type Case3 = EmptyString<string>;
+ * // ➔ never
+ *
+ * // With leading/trailing whitespace
+ * type Case4 = EmptyString<"  ", true>;
+ * // ➔ "" (trimmed)
+ * type Case5 = EmptyString<"  ", false>;
+ * // ➔ never (not trimmed)
+ * ```
+ */
+type EmptyString<T extends string,WithTrim extends boolean=true>=""extends(WithTrim extends true?Trim<T>:T)?string extends(WithTrim extends true?Trim<T>:T)?never:WithTrim extends true?Trim<T>:T:never;
+/** -------------------------------------------------------
+ * * ***NonEmptyString.***
+ * -------------------------------------------------------
+ * Returns the type `T` only if it is a non-empty string.
+ * Optionally trims whitespace before checking.
+ *
+ * Behavior:
+ * - If `WithTrim` is `true` (default), trims `T` before checking.
+ * - If `T` is the general `string` type, returns `string`.
+ * - If `T` is empty (after optional trimming), returns `never`.
+ *
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ *
+ * @example
+ * ```ts
+ * // Non-empty string
+ * type Case1 = NonEmptyString<"abc">; // ➔ "abc"
+ *
+ * // Empty string
+ * type Case2 = NonEmptyString<"">; // ➔ never
+ *
+ * // General string type
+ * type Case3 = NonEmptyString<string>; // ➔ string
+ *
+ * // String with whitespace
+ * type Case4 = NonEmptyString<"  ", true>; // ➔ never (trimmed to empty)
+ * type Case5 = NonEmptyString<"  ", false>; // ➔ "  " (not trimmed)
+ * ```
+ */
+type NonEmptyString<T extends string,WithTrim extends boolean=true>=string extends T?string:If<IsNever<EmptyString<T,WithTrim>>,WithTrim extends true?Trim<T>:T,never>;
+/** -------------------------------------------------------
+ * * ***IsEmptyString.***
+ * -------------------------------------------------------
+ * Returns `true` if `T` is exactly the empty string `""`.
+ * Optionally trims whitespace before checking.
+ *
+ * Behavior:
+ * - If `WithTrim` is `true` (default), trims `T` before checking.
+ * - If `T` is empty after optional trimming, returns `true`.
+ * - Otherwise, returns `false`.
+ *
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ *
+ * @example
+ * ```ts
+ * type Case1 = IsEmptyString<"">;
+ * // ➔ true
+ * type Case2 = IsEmptyString<"abc">;
+ * // ➔ false
+ * type Case3 = IsEmptyString<"  ", true>;
+ * // ➔ true (trimmed)
+ * type Case4 = IsEmptyString<"  ", false>;
+ * // ➔ false (not trimmed)
+ * ```
+ */
+type IsEmptyString<T extends string,WithTrim extends boolean=true>=IfNot<IsNever<EmptyString<T,WithTrim>>>;
+/** -------------------------------------------------------
+ * * ***IsNonEmptyString.***
+ * -------------------------------------------------------
+ * Returns `true` if `T` is a non-empty string.
+ * Optionally trims whitespace before checking.
+ *
+ * Behavior:
+ * - If `WithTrim` is `true` (default), trims `T` before checking.
+ * - Returns `true` if `T` is non-empty after optional trimming.
+ * - Returns `false` if `T` is empty (after trimming if `WithTrim=true`).
+ *
+ * @template T - The string type to check.
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ *
+ * @example
+ * ```ts
+ * type Case1 = IsNonEmptyString<"abc">;
+ * // ➔ true
+ * type Case2 = IsNonEmptyString<"">;
+ * // ➔ false
+ * type Case3 = IsNonEmptyString<"  ", true>;
+ * // ➔ false (trimmed)
+ * type Case4 = IsNonEmptyString<"  ", false>;
+ * // ➔ true (not trimmed)
+ * ```
+ */
+type IsNonEmptyString<T extends string,WithTrim extends boolean=true>=IfNot<IsNever<NonEmptyString<T,WithTrim>>>;
+/** -------------------------------------------------------
+ * * ***IfEmptyString.***
+ * -------------------------------------------------------
+ * Conditional type: returns `IfTrue` if `T` is an empty string `""`,
+ * otherwise returns `IfFalse`. Optionally trims whitespace before checking.
+ *
+ * @template T - The string type to check.
+ * @template IfTrue - Type returned if `T` is empty (default `true`).
+ * @template IfFalse - Type returned if `T` is not empty (default `false`).
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ *
+ * @example
+ * ```ts
+ * type Case1 = IfEmptyString<"">;
+ * // ➔ true
+ * type Case2 = IfEmptyString<"abc">;
+ * // ➔ false
+ * type Case3 = IfEmptyString<"", "yes", "no">;
+ * // ➔ "yes"
+ * type Case4 = IfEmptyString<"abc", "yes", "no">;
+ * // ➔ "no"
+ * type Case5 = IfEmptyString<"  ", "yes", "no", true>;
+ * // ➔ "yes" (trimmed)
+ * type Case6 = IfEmptyString<"  ", "yes", "no", false>;
+ * // ➔ "no" (not trimmed)
+ * ```
+ */
+type IfEmptyString<T extends string,IfTrue=true,IfFalse=false,WithTrim extends boolean=true>=IfNot<IsNever<EmptyString<T,WithTrim>>,IfTrue,IfFalse>;
+/** -------------------------------------------------------
+ * * ***IfNonEmptyString.***
+ * -------------------------------------------------------
+ * Conditional type: returns `IfTrue` if `T` is a non-empty string,
+ * otherwise returns `IfFalse`. Optionally trims whitespace before checking.
+ *
+ * @template T - The string type to check.
+ * @template IfTrue - Type returned if `T` is non-empty (default `true`).
+ * @template IfFalse - Type returned if `T` is empty (default `false`).
+ * @template WithTrim - Whether to trim whitespace before checking (default `true`).
+ *
+ * @example
+ * ```ts
+ * type Case1 = IfNonEmptyString<"abc">;
+ * // ➔ true
+ * type Case2 = IfNonEmptyString<"">;
+ * // ➔ false
+ * type Case3 = IfNonEmptyString<"abc", "yes", "no">;
+ * // ➔ "yes"
+ * type Case4 = IfNonEmptyString<"", "yes", "no">;
+ * // ➔ "no"
+ * type Case5 = IfNonEmptyString<"  ", "yes", "no", true>;
+ * // ➔ "no" (trimmed)
+ * type Case6 = IfNonEmptyString<"  ", "yes", "no", false>;
+ * // ➔ "yes" (not trimmed)
+ * ```
+ */
+type IfNonEmptyString<T extends string,IfTrue=true,IfFalse=false,WithTrim extends boolean=true>=IfNot<IsNever<NonEmptyString<T,WithTrim>>,IfTrue,IfFalse>;export type{AnyString as A,EmptyString as E,IfNot as I,NonEmptyString as N,Trim as T,Whitespace as W,IsEmptyString as a,IfEmptyString as b,WordSeparator as c,IfNonEmptyString as d,IsNonEmptyString as e,TrimLeft as f,TrimRight as g,TrimsLower as h,TrimsUpper as i};

package/dist/strings/index.cjs

@@ -1 +1 @@
-'use strict';var chunkTUXDINHF_cjs=require('../chunk-TUXDINHF.cjs'),chunkN2IJPIND_cjs=require('../chunk-N2IJPIND.cjs');require('../chunk-2TRAPBZ7.cjs');var chunkCN53M4QZ_cjs=require('../chunk-CN53M4QZ.cjs');Object.defineProperty(exports,"getInitialsName",{enumerable:true,get:function(){return chunkTUXDINHF_cjs.b}});Object.defineProperty(exports,"replaceAt",{enumerable:true,get:function(){return chunkTUXDINHF_cjs.a}});Object.defineProperty(exports,"normalizeSpaces",{enumerable:true,get:function(){return chunkN2IJPIND_cjs.a}});Object.defineProperty(exports,"normalizeString",{enumerable:true,get:function(){return chunkN2IJPIND_cjs.b}});Object.defineProperty(exports,"removeSpaces",{enumerable:true,get:function(){return chunkN2IJPIND_cjs.c}});Object.defineProperty(exports,"stripHtmlTags",{enumerable:true,get:function(){return chunkN2IJPIND_cjs.d}});Object.defineProperty(exports,"capitalizeFirst",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.s}});Object.defineProperty(exports,"capitalizeWords",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.t}});Object.defineProperty(exports,"slugify",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.B}});Object.defineProperty(exports,"toCamelCase",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.u}});Object.defineProperty(exports,"toDotCase",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.A}});Object.defineProperty(exports,"toKebabCase",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.y}});Object.defineProperty(exports,"toLowerCase",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.x}});Object.defineProperty(exports,"toPascalCase",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.w}});Object.defineProperty(exports,"toPascalCaseSpace",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.v}});Object.defineProperty(exports,"toSnakeCase",{enumerable:true,get:function(){return chunkCN53M4QZ_cjs.z}});
+'use strict';var chunkIW73G523_cjs=require('../chunk-IW73G523.cjs'),chunkMROH35V3_cjs=require('../chunk-MROH35V3.cjs');require('../chunk-UTQUYABU.cjs');var chunkCII6WWLO_cjs=require('../chunk-CII6WWLO.cjs');Object.defineProperty(exports,"getInitialsName",{enumerable:true,get:function(){return chunkIW73G523_cjs.b}});Object.defineProperty(exports,"replaceAt",{enumerable:true,get:function(){return chunkIW73G523_cjs.a}});Object.defineProperty(exports,"normalizeSpaces",{enumerable:true,get:function(){return chunkMROH35V3_cjs.a}});Object.defineProperty(exports,"normalizeString",{enumerable:true,get:function(){return chunkMROH35V3_cjs.b}});Object.defineProperty(exports,"removeSpaces",{enumerable:true,get:function(){return chunkMROH35V3_cjs.c}});Object.defineProperty(exports,"stripHtmlTags",{enumerable:true,get:function(){return chunkMROH35V3_cjs.d}});Object.defineProperty(exports,"capitalizeFirst",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.s}});Object.defineProperty(exports,"capitalizeWords",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.t}});Object.defineProperty(exports,"slugify",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.B}});Object.defineProperty(exports,"toCamelCase",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.u}});Object.defineProperty(exports,"toDotCase",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.A}});Object.defineProperty(exports,"toKebabCase",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.y}});Object.defineProperty(exports,"toLowerCase",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.x}});Object.defineProperty(exports,"toPascalCase",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.w}});Object.defineProperty(exports,"toPascalCaseSpace",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.v}});Object.defineProperty(exports,"toSnakeCase",{enumerable:true,get:function(){return chunkCII6WWLO_cjs.z}});