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

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 chunkXOYX4PLZ_cjs=require('../chunk-XOYX4PLZ.cjs'),chunk445TAVT4_cjs=require('../chunk-445TAVT4.cjs');require('../chunk-6Q4I2RPC.cjs');var chunkLVUSFXQS_cjs=require('../chunk-LVUSFXQS.cjs');Object.defineProperty(exports,"getInitialsName",{enumerable:true,get:function(){return chunkXOYX4PLZ_cjs.b}});Object.defineProperty(exports,"replaceAt",{enumerable:true,get:function(){return chunkXOYX4PLZ_cjs.a}});Object.defineProperty(exports,"normalizeSpaces",{enumerable:true,get:function(){return chunk445TAVT4_cjs.a}});Object.defineProperty(exports,"normalizeString",{enumerable:true,get:function(){return chunk445TAVT4_cjs.b}});Object.defineProperty(exports,"removeSpaces",{enumerable:true,get:function(){return chunk445TAVT4_cjs.c}});Object.defineProperty(exports,"stripHtmlTags",{enumerable:true,get:function(){return chunk445TAVT4_cjs.d}});Object.defineProperty(exports,"capitalizeFirst",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.s}});Object.defineProperty(exports,"capitalizeWords",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.t}});Object.defineProperty(exports,"slugify",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.B}});Object.defineProperty(exports,"toCamelCase",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.u}});Object.defineProperty(exports,"toDotCase",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.A}});Object.defineProperty(exports,"toKebabCase",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.y}});Object.defineProperty(exports,"toLowerCase",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.x}});Object.defineProperty(exports,"toPascalCase",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.w}});Object.defineProperty(exports,"toPascalCaseSpace",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.v}});Object.defineProperty(exports,"toSnakeCase",{enumerable:true,get:function(){return chunkLVUSFXQS_cjs.z}});