@rzl-zone/utils-js 3.3.0 → 3.4.0

package/dist/string-B1jlOnws.d.ts

@@ -1,312 +0,0 @@
-import{I as If}from'./if-ChM35c_q.js';import{I as IsNever}from'./never-D89PbPh5.js';
-/** -------------------------------------------------------
- * * ***Utility Type: `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`).
- * @example
- * ```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>;
-/** -------------------------------------------------------
- * * ***Utility Type: `WordSeparator`.***
- * -------------------------------------------------------
- * **A type-level utility that defines all valid ***word separators***.**
- * - Can be a space `" "`, a dash `"-"`, or an underscore `"_"`.
- * @example
- * type A = WordSeparator; // ➔ " " | "-" | "_"
- */
-type WordSeparator=" "|"-"|"_";
-/** --------------------------------------------------
- * * ***Utility Type: `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 Type Internal.** */
-type SafeKeyTrimming<T>=Exclude<T,symbol>;
-/** --------------------------------------------------
- * * ***Utility Type: `TrimLeft`.***
- * --------------------------------------------------
- * **Recursively trims specified characters (default: **{@link Whitespace | `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;
-/** --------------------------------------------------
- * * ***Utility Type: `TrimRight`.***
- * --------------------------------------------------
- * **Recursively trims specified characters (default: **{@link Whitespace | `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;
-/** --------------------------------------------------
- * * ***Utility Type: `Trim`.***
- * --------------------------------------------------
- * **Trims specified characters (default: **{@link Whitespace | `Whitespace`}**)
- * from **both the start and end** of a string.**
- * @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>;
-/** -------------------------------------------------------
- * * ***Utility Type: `TrimsLower`.***
- * -------------------------------------------------------
- * **Trims leading & trailing whitespace from a string and
- * converts it to **lowercase**.**
- * @description
- * Utilizes **{@link Trim | `Trim`}** to remove whitespace and
- * **{@link Lowercase | `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>>;
-/** -------------------------------------------------------
- * * ***Utility Type: `TrimsUpper`.***
- * -------------------------------------------------------
- * **Trims leading & trailing whitespace from a string and
- * converts it to **uppercase**.**
- * @description
- * Utilizes **{@link Trim | `Trim`}** to remove whitespace and
- * **{@link Uppercase | `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>>;
-/** -------------------------------------------------------
- * * ***Utility Type: `AnyString`.***
- * -------------------------------------------------------
- * **A utility type that represents **any string value** while
- * preventing unwanted widening of string literals to `string`.**
- * @description
- * 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;
-/** -------------------------------------------------------
- * * ***Utility Type: `EmptyString`.***
- * -------------------------------------------------------
- * - **Conditional type:**
- *    - 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;
-/** -------------------------------------------------------
- * * ***Utility Type: `NonEmptyString`.***
- * -------------------------------------------------------
- * - **Conditional type:**
- *    - 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>;
-/** -------------------------------------------------------
- * * ***Utility Type: `IsEmptyString`.***
- * -------------------------------------------------------
- * - **Conditional type:**
- *    - 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>>>;
-/** -------------------------------------------------------
- * * ***Utility Type: `IsNonEmptyString`.***
- * -------------------------------------------------------
- * - **Conditional type:**
- *    - 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>>>;
-/** -------------------------------------------------------
- * * ***Utility Type: `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>;
-/** -------------------------------------------------------
- * * ***Utility Type: `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};