toolbox-x 1.0.0

package/dist/string-CsNsm_65.d.cts

@@ -0,0 +1,258 @@
+/**
+ * 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 { t as LOWERCASE } from "./constants-B34K0QPi.cjs";
+import { In as Join, t as $Countries, ur as Split, zn as LooseLiteral } from "./object-Blq0Amdv.cjs";
+
+//#region src/types/string.d.ts
+declare global {
+  interface String {
+    toLowerCase(): string;
+    /**
+     * * Converts all the alphabetic characters in a string to lowercase.
+     *
+     * @typeParam `Lower` - A type-level flag. If `'T'`, returns the lowercase string type (`Lowercase<string>`). Otherwise, returns literal `Lower` (must be Lowercase type).
+     *
+     * @remarks
+     * - This augmentation only affects TypeScript type inference.
+     * - Runtime behavior remains identical to the standard `toLowerCase()` method.
+     */
+    toLowerCase<Lower extends 'T' | Lowercase<string>>(): Lower extends 'T' ? Lowercase<string> : Lower;
+    toUpperCase(): string;
+    /**
+     * * Converts all the alphabetic characters in a string to uppercase.
+     *
+     * @typeParam `Upper` - A type-level flag. If `'T'`, returns the uppercase string type (`Uppercase<string>`). Otherwise, returns literal `Upper` (must be Uppercase type).
+     *
+     * @remarks
+     * - This augmentation only affects TypeScript type inference.
+     * - Runtime behavior remains identical to the standard `toUpperCase()` method.
+     */
+    toUpperCase<Upper extends 'T' | Uppercase<string>>(): Upper extends 'T' ? Uppercase<string> : Upper;
+  }
+}
+/** - Options for generating anagrams. */
+interface AnagramOptions {
+  /**
+   * Maximum number of anagrams to generate.
+   * Defaults to `100`. Pass `"all"` to return all possible anagrams.
+   */
+  limit?: number | 'all';
+  /**
+   * Optional dictionary array of strings for validating anagrams.
+   * - Pass `false` (default) to skip dictionary lookup.
+   * - Pass an array of strings to include only anagrams present in that array.
+   * - Dictionary lookup is case-insensitive; internally, a cached lowercase `Set` is used for performance.
+   * - Duplicate entries in the dictionary are ignored.
+   */
+  dictionary?: false | string[];
+}
+/** - Options for `capitalizeString` function. */
+interface CapitalizeOptions {
+  /** If true, capitalizes the first letter of each word (space separated). Defaults to `false`. */
+  capitalizeEachFirst?: boolean;
+  /** If true, ensures that the whole string is capitalized. Defaults to `false`. */
+  capitalizeAll?: boolean;
+  /** If true, ensures that the rest of the string is lowercase. Defaults to `true`. */
+  lowerCaseRest?: boolean;
+}
+/** - Configuration options for ID generation. */
+interface RandomIdOptions {
+  /** A string to prepend to the ID. Default is an empty string. */
+  prefix?: string;
+  /** A string to append to the ID. Default is an empty string.*/
+  suffix?: string;
+  /** Whether to include the current timestamp in the ID. Default is `false`. */
+  timeStamp?: boolean;
+  /** The length of the random alphanumeric string. Default is `16`. */
+  length?: number;
+  /** The separator to use between parts of the ID. Default is an empty string. */
+  separator?: string;
+  /** Specifies the case for the full id (this includes alphanumeric string and suffix+prefix). Default is `null`. */
+  caseOption?: 'upper' | 'lower' | null;
+}
+/** - Case formats for converting a string */
+type CaseFormat = 'camelCase' | 'snake_case' | 'kebab-case' | 'PascalCase' | 'Title Case' | 'Sentence case' | 'UPPERCASE' | 'lowercase';
+/** * Options for `convertStringCase`. */
+interface StringCaseOptions {
+  /**
+   * Preserve acronym-like tokens (tokens that are ALL UPPERCASE with length >= 2)
+   * when converting to PascalCase / Title Case / camelCase (mid tokens).
+   *
+   * Behavior summary:
+   * - PascalCase: keep acronyms intact (API -> API).
+   * - camelCase: first token acronyms are lowercased entirely (API -> api),
+   *   subsequent token acronyms are preserved (API -> API).
+   * - Title Case: acronym tokens are preserved (API).
+   * - snake_case / kebab-case: tokens are lowercased (xml-http-request).
+   */
+  preserveAcronyms?: boolean;
+}
+/** Options for masking a string. */
+interface MaskOptions {
+  /** Number of characters to keep at the start. Defaults to `1`. */
+  start?: number;
+  /** Number of characters to keep at the end. Defaults to `1`. */
+  end?: number;
+  /** Character to use for masking. Defaults to `*`. */
+  maskCharacter?: string;
+}
+/** Formatted query string as `?${string}` = `?key=value&...` or empty string. */
+type QueryString = `?${string}` | '';
+/** Full country name */
+type CountryName = $Countries['country_name'];
+/** Country code, e.g. `"880" | "973" | "994" | "1-242" ...` */
+type CountryCode = $Countries['country_code'];
+/** ISO country country codes (3-character), e.g. `"BGD" | "BRB" | "BLR" ...` */
+type CountryISO = $Countries['iso_code'];
+/** ISO country country codes (2-character), e.g. `"BD" | "BB" | "BY" ...` */
+type CountryShortISO = $Countries['iso_code_short'];
+/** ISO 2 character country code or any string */
+type Country = LooseLiteral<CountryShortISO>;
+/** Lowercase prepositions, articles, conjunctions, and auxiliary verbs ({@link LOWERCASE}) */
+type $LowerCaseWord = (typeof LOWERCASE)[number];
+/** Ensure early inference and string constraint. */
+type $EnsureString<Str> = Str extends string ? Str : never;
+/** Check if a string literal `Str` contains a substring `SubStr` */
+type Includes<Str extends string, SubStr extends string> = Str extends `${string}${SubStr}${string}` ? true : false;
+/** Trim leading space from a string literal */
+type $TrimLeft<Str extends string> = Str extends ` ${infer R}` ? $TrimLeft<R> : Str;
+/** Trim trailing space from a string literal */
+type $TrimRight<Str extends string> = Str extends `${infer L} ` ? $TrimRight<L> : Str;
+/** Trim leading and trailing spaces from a string literal */
+type Trim<Str extends string> = $TrimRight<$TrimLeft<Str>>;
+/** Default delimiter characters */
+type $DefaultDelimiters = ' ' | '-' | '_' | '.' | '/';
+/** Turn user delim string like "*+," into '*, +, ,' union */
+type $UserDelimiters<Del extends string> = Del extends '' ? never : Del extends `${infer C}${infer R}` ? C | $UserDelimiters<R> : never;
+/** Is char `C` a delimiter (either default or user-provided)? */
+type $IsDelimiter<C extends string, Del extends string> = C extends $DefaultDelimiters ? true : C extends $UserDelimiters<Del> ? true : false;
+/** Insert space before capital letters: "helloWorld" -> "hello World" */
+type $SpaceBeforeCaps<Str extends string> = Str extends `${infer F}${infer R}` ? R extends Uncapitalize<R> ? `${F}${$SpaceBeforeCaps<R>}` : `${F} ${$SpaceBeforeCaps<R>}` : Str;
+/** Replace delimiter(s) with space(s) */
+type $ReplaceDelimiters<Str extends string, Del extends string, Acc extends string = '', LastWasSpace extends boolean = false> = Str extends `${infer F}${infer R}` ? $IsDelimiter<F, Del> extends true ? $ReplaceDelimiters<R, Del, Acc extends '' ? ' ' : LastWasSpace extends true ? Acc : `${Acc} `, true> : $ReplaceDelimiters<R, Del, `${Acc}${F}`, false> : Acc;
+/** Normalize {@link $DefaultDelimiters} or {@link $UserDelimiters} `Del` in a string literal `Str` with space(s) */
+type $NormalizeString<Str extends string, Del extends string = ''> = Trim<$ReplaceDelimiters<$SpaceBeforeCaps<Str>, Del, '', false>>;
+/** Lowercase all the words in a tuple */
+type $LowercaseWords<T extends readonly string[]> = T extends [infer H extends string, ...infer R extends string[]] ? [Lowercase<H>, ...$LowercaseWords<R>] : [];
+/** Uppercase all the words in a tuple */
+type $UppercaseWords<T extends readonly string[]> = T extends [infer H extends string, ...infer R extends string[]] ? [Uppercase<Lowercase<H>>, ...$UppercaseWords<R>] : [];
+/** Capitalize (first letter capital) all the words in a tuple */
+type $CapitalizeWords<T extends readonly string[]> = T extends [infer H extends string, ...infer R extends string[]] ? [Capitalize<Lowercase<H>>, ...$CapitalizeWords<R>] : [];
+/** Capitalize (first letter capital) all the words in a tuple */
+type $TitleCaseWords<T extends readonly string[]> = T extends [infer H extends string, ...infer R extends string[]] ? [H extends $LowerCaseWord ? Lowercase<H> : Capitalize<Lowercase<H>>, ...$TitleCaseWords<R>] : [];
+/**
+ * - Converts a string literal `Str` into `camelCase`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type CamelCase<Str extends string, Del extends string = ''> = Split<$NormalizeString<Str, Del>, ' '> extends [infer F extends string, ...infer R extends string[]] ? `${Lowercase<F>}${Join<$CapitalizeWords<R>, ''>}` : '';
+/**
+ * - Converts a string literal `Str` into `snake_case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type SnakeCase<Str extends string, Del extends string = ''> = Join<$LowercaseWords<Split<$NormalizeString<Str, Del>, ' '>>, '_'>;
+/**
+ * - Converts a string literal `Str` into `kebab-case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type KebabCase<Str extends string, Del extends string = ''> = Join<$LowercaseWords<Split<$NormalizeString<Str, Del>, ' '>>, '-'>;
+/**
+ * - Converts a string literal `Str` into `PascalCase`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type PascalCase<Str extends string, Del extends string = ''> = Join<$CapitalizeWords<Split<$NormalizeString<Str, Del>, ' '>>, ''>;
+/**
+ * - Converts a string literal `Str` into `Pascal_Snake_Case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type PascalSnakeCase<Str extends string, Del extends string = ''> = Join<$CapitalizeWords<Split<$NormalizeString<Str, Del>, ' '>>, '_'>;
+/**
+ * - Converts a string literal `Str` into `CONSTANT_CASE`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type ConstantCase<Str extends string, Del extends string = ''> = Join<$UppercaseWords<Split<$NormalizeString<Str, Del>, ' '>>, '_'>;
+/**
+ * - Converts a string literal `Str` into `Train-Case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type TrainCase<Str extends string, Del extends string = ''> = Join<$CapitalizeWords<Split<$NormalizeString<Str, Del>, ' '>>, '-'>;
+/**
+ * - Converts a string literal `Str` into `Dot.Case`/`dot.case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type DotCase<Str extends string, Del extends string = ''> = Join<Split<$NormalizeString<Str, Del>, ' '>, '.'>;
+/**
+ * - Converts a string literal `Str` into `path/case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks TypeScript supports up to ~45 characters for reliable literal inference.
+ */
+type PathCase<Str extends string, Del extends string = ''> = Join<$LowercaseWords<Split<$NormalizeString<Str, Del>, ' '>>, '/'>;
+/**
+ * - Converts a string literal `Str` into `Title Case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks
+ * - TypeScript supports up to ~45 characters for reliable literal inference.
+ * - Lowercase auxiliaries, prepositions, articles and conjunctions unless they are at the beginning.
+ */
+type TitleCase<Str extends string, Del extends string = ''> = Split<$NormalizeString<Str, Del>, ' '> extends [infer F extends string, ...infer R extends string[]] ? `${Capitalize<Lowercase<F>>} ${Join<$TitleCaseWords<R>, ' '>}` : ' ';
+/**
+ * - Converts a string literal `Str` into `Sentence case`, using optional custom delimiters `Del` alongside {@link $DefaultDelimiters}.
+ * @remarks It will lowercase: auxiliaries, prepositions, articles and conjunctions unless they are at the beginning.
+ */
+type SentenceCase<Str extends string, Del extends string = ''> = Split<$NormalizeString<Str, Del>, ' '> extends [infer F extends string, ...infer R extends string[]] ? `${Capitalize<Lowercase<F>>} ${Join<$LowercaseWords<R>, ' '>}` : ' ';
+/** Matches any non-Latin character. */
+type SpecialCharacter = Lowercase<string> & Uppercase<string>;
+/** Evaluates whether a string consists only of Latin alphabet characters. */
+type IsAlphabet<T extends string> = T extends `${infer Head}${infer Tail}` ? Head extends SpecialCharacter ? false : IsAlphabet<Tail> : true;
+/** Restricts a string to Latin-only characters; otherwise resolves to never. */
+type Alphabet<T extends string> = IsAlphabet<T> extends true ? T : never;
+/** Types related to string diffing and similarity calculations. */
+type DiffLineType = 'added' | 'removed' | 'unchanged' | 'modified';
+/** A single line difference between two strings, including the type of difference and the content of the line in both original and modified strings. */
+interface DiffLine {
+  /** The type of difference: 'added', 'removed', 'unchanged', or 'modified'. */
+  type: DiffLineType;
+  /** The content of the original line. Undefined for added lines. */
+  original?: string;
+  /** The content of the modified line. Undefined for removed lines. */
+  modified?: string;
+  /** The line number in the original string (1-based). Undefined for added lines. */
+  originalLineNum?: number;
+  /** The line number in the modified string (1-based). Undefined for removed lines. */
+  modifiedLineNum?: number;
+}
+/** The result of a line-level diff operation, including an array of line differences and summary statistics. */
+interface DiffResult {
+  /** An array of line differences, where each line is categorized as 'added', 'removed', 'unchanged', or 'modified'. */
+  lines: DiffLine[];
+  /** Statistics summarizing the diff results, including counts of added, removed, changed, and unchanged lines. */
+  stats: {
+    /** Total number of lines that were added in the modified string compared to the original. */linesAdded: number; /** Total number of lines that were removed from the original string in the modified version. */
+    linesRemoved: number; /** Total number of lines that were modified (changed content) between the original and modified strings. */
+    linesChanged: number; /** Total number of lines that remained unchanged between the original and modified strings. */
+    linesUnchanged: number;
+  };
+}
+/** A single character annotated with a `highlighted` flag indicating whether it differs from the other string in a diff operation. */
+type HighlightedText = {
+  text: string;
+  highlighted: boolean;
+};
+/** Result of a character-level diff, mapping each character in both strings to a `highlighted` flag. */
+type CharDiffResult = {
+  /** An array of characters from the original string, each annotated with a `highlighted` flag indicating whether it differs from the modified string. */original: HighlightedText[]; /** An array of characters from the modified string, each annotated with a `highlighted` flag indicating whether it differs from the original string. */
+  modified: HighlightedText[];
+};
+//#endregion
+export { MaskOptions as A, TitleCase as B, DiffLineType as C, Includes as D, HighlightedText as E, RandomIdOptions as F, Trim as H, SentenceCase as I, SnakeCase as L, PascalSnakeCase as M, PathCase as N, IsAlphabet as O, QueryString as P, SpecialCharacter as R, DiffLine as S, DotCase as T, TrainCase as V, Country as _, $NormalizeString as a, CountryName as b, $TrimRight as c, AnagramOptions as d, CamelCase as f, ConstantCase as g, CharDiffResult as h, $LowercaseWords as i, PascalCase as j, KebabCase as k, $UppercaseWords as l, CaseFormat as m, $EnsureString as n, $TitleCaseWords as o, CapitalizeOptions as p, $LowerCaseWord as r, $TrimLeft as s, $CapitalizeWords as t, Alphabet as u, CountryCode as v, DiffResult as w, CountryShortISO as x, CountryISO as y, StringCaseOptions as z };