@lntvow/utils 4.1.0 → 4.2.0

package/dist/utils.esm-bundler.d.ts

@@ -243,84 +243,84 @@ interface PickOptions {
 }
 
 /**
- * 生成随机数组
+ * Generate random array
  * @example generateRandomArray(4, () => 1) => [1, 1, 1, 1]
  * */
 declare function generateRandomArray<T>(num: number, cb: (item?: unknown, index?: number) => T): T[];
 
 /**
- * 生成随机颜色
+ * Generate random color
  * @example generateRandomColor() => '#f36a38'
  * */
 declare function generateRandomColor(): string;
 
 /**
- * 生成随机时间
+ * Generate random date
  * @example generateRandomDate() => '2021-07-01 08:51:34'
  * */
 declare function generateRandomDate(options?: GenerateRandomDate): string;
 interface GenerateRandomDate {
     /**
-     * 开始时间
+     * Start time
      * @default 1800-01-01 00:00:00
      */
     start?: string | Date;
     /**
-     * 结束时间
-     * @default 当前时间
+     * End time
+     * @default Current time
      */
     end?: string | Date;
     /**
-     * 时间格式
+     * Date format
      * @default YYYY-MM-DD HH:mm:ss
      */
     format?: string;
 }
 
 /**
- * 生成随机邮箱
+ * Generate random email
  * @example generateRandomEmail() => lZtJqMl0dyTO3WDGzFDO@gmail.com
  */
 declare function generateRandomEmail(): string;
 
 /**
- * 生成范围内的随机浮点数
+ * Generate random float number within range
  * @example generateRandomFloat() => 0.35
  * */
 declare function generateRandomFloat(options?: GenerateRandomFloat): number;
 type GenerateRandomFloat = number | {
     /**
-     * 最大值
+     * Maximum value
      * @default 1.00
      */
     max?: number;
     /**
-     * 最小值
+     * Minimum value
      * @default 0.00
      */
     min?: number;
     /**
-     * 小数位数
+     * Fraction digits
      * @default  2
      */
     fractionDigits?: number;
 };
 
 /**
- * 生成随机二代身份证号
+ * Generate random Chinese ID card number
  * @example generateRandomIdCard() => '410304200210165258'
  */
 declare function generateRandomIdCard(): string;
 
 /**
- * 生成随机手机号码
+ * Generate random mobile phone number
  * @example generateRandomMobilePhone() => 13012345678
  */
 declare function generateRandomMobilePhone(): string;
 
 /**
- * 生成随机数据从数据源中
- * @param num  随机获取数据源子项次数
+ * Generate random string from source
+ * @param num Number of times to randomly get items from source
  * @example generateRandomStringFromSource(4, ['1', 'b', 'c', 'd', 'e']) => 'dea1'
  * */
 declare function generateRandomStringFromSource(num: number, source: (number | string)[]): string;
@@ -356,7 +356,7 @@ type Options$1 = {
  | number;
 
 /**
- * 获取数组中的随机元素
+ * Get random item from array
  * @example  getRandomItem([0, 1, 2, 3, 4]) => 2
  */
 declare function getRandomItem<T>(list: T[]): T;
@@ -426,76 +426,125 @@ type Options = {
 declare function getRandomUrl(): string;
 
 /**
- * 十进制转二进制
+ * Convert decimal to binary
  * @example decimalToBinary(233) => '11101001'
  */
 declare function decimalToBinary(decNumber: number): string;
 /**
- * Base64 编码
+ * Base64 encode
  * @example base64Encode('hello') => 'aGVsbG8='
  */
 declare function base64Encode(str: string): string;
 /**
- * Base64 解码
+ * Base64 decode
  * @example base64Decode('aGVsbG8=') => 'hello'
  */
 declare function base64Decode(str: string): string;
 
 /**
  * compose
- * @param fns 任意函数
+ * @param fns Any functions
  */
 declare function compose(...fns: ((...args: any[]) => any)[]): (...args: any[]) => any;
 /**
- * compose 从右到左
- * @param fns 任意函数
+ * Compose from right to left
+ * @param fns Any functions
  */
 declare function composeRight(...fns: ((...args: any[]) => any)[]): (...args: any[]) => any;
 
 /**
- * 防抖函数
- * @param target 目标函数
- * @param wait 等待时间 默认 500ms
+ * Debounce function
+ * @param target Target function
+ * @param wait Wait time, default 500ms
  * @example debounce(() => console.log('debounce'), 500)
  */
 declare function debounce(target: Function, wait?: number): (...args: any[]) => void;
 
 /**
- * Deeply clones an object
- * @param target The target object to clone
- * @example
+ * Creates a deep clone of any value, preserving object structure and references.
+ *
+ * This utility performs a complete deep copy of the input value, handling complex nested structures,
+ * circular references, and various JavaScript types. It preserves prototype chains, property descriptors,
+ * and handles special objects like Date, RegExp, Map, Set, and more.
  *
+ * @example
  * deepClone({ name: 'test' }) => { name: 'test' }
+ *
+ * @example
+ * deepClone({ user: { name: 'John', data: [1, 2] } }) => { user: { name: 'John', data: [1, 2] } }
+ *
+ * @returns A deep clone of the input value with all nested references copied
+ *
+ * @remarks
+ * - Handles circular references to prevent infinite loops
+ * - Preserves prototype chains for objects and arrays
+ * - Maintains property descriptors including getters and setters
+ * - Supports Symbol properties and Symbol keys
+ * - Clones Date objects to new Date instances with same time
+ * - Clones RegExp objects maintaining their behavior
+ * - Returns Promise objects as-is (promises are not cloned)
+ * - Recursively clones Map and Set collections including their keys/values
+ * - Handles non-object-like values (primitives) by returning them directly
+ * - Preserves array subclass prototypes and custom array-like objects
+ * - Maintains all property metadata and descriptors
  */
 declare function deepClone<T>(target: T): T;
 
 /**
- * Deeply merges two objects
- * @param template The template object, which serves as the default values
- * @param source The source object, which contains user-provided values
- * @param options Configuration options
+ * Recursively merges two objects into a single combined object.
+ *
+ * This utility performs a deep merge operation, combining properties from a template object
+ * (default values) with a source object (user-provided values). The function handles nested
+ * objects, arrays, and preserves property descriptors. It supports different merge strategies
+ * for arrays and optional deep cloning to prevent mutation of original objects.
+ *
  * @example
+ * deepMerge({ name: 'John', age: 25 }, { age: 30, city: 'NYC' }) => { name: 'John', age: 30, city: 'NYC' }
  *
- * deepMerge({ name: 1 }, { test: 'test' }) => { name: 1, test: 'test' }
+ * @example
+ * deepMerge({ data: { x: 1 } }, { data: { y: 2 } }) => { data: { x: 1, y: 2 } }
  *
- * deepMerge({ x: [1, 2] }, { y: [3, 4] }) => { x: [1, 2], y: [3, 4] }
+ * @returns A new merged object combining properties from both template and source
+ *
+ * @remarks
+ * - Template object provides default values and structure
+ * - Source object values override template values for matching keys
+ * - Nested objects are recursively merged rather than replaced
+ * - Arrays can be merged or replaced based on mergeStrategy option
+ * - Property descriptors (getters, setters, etc.) are preserved
+ * - Deep cloning is enabled by default to prevent original object mutation
+ * - Non-plain objects in source will replace corresponding template values
+ * - Supports Symbol properties and maintains prototype relationships
  */
 declare function deepMerge(template: AnyObject, source: AnyObject, options?: DeepMergeOptions): any;
 interface DeepMergeOptions {
     /**
-     * Enable deep cloning
+     * Controls whether to create deep clones of input objects before merging.
+     *
+     * When enabled, both template and source objects are deep cloned before the merge
+     * operation, ensuring the original objects remain unmodified. When disabled,
+     * the merge operates directly on the provided objects, which may result in mutation.
+     *
      * @default true
      */
     deepClone?: boolean;
     /**
-     * Merge strategy for arrays
+     * Determines how arrays should be handled during the merge process.
+     *
+     * - 'merge': Concatenates arrays from template and source (template + source)
+     * - 'replace': Source array completely replaces the template array
+     *
+     * This only applies when both template and source have arrays at the same key.
+     * If only one side has an array, it will be used as-is regardless of strategy.
+     *
      * @default 'replace'
-     * - 'merge': Merges the arrays
-     * - 'replace': Replaces the array with the new one
      */
     mergeStrategy?: 'merge' | 'replace';
 }
 
+declare class UtilsError extends Error {
+    constructor(m: string, name?: string);
+}
 declare function throwError(scope: string, message: string): void;
 declare function debugWarn(err: Error): void;
 declare function debugWarn(scope: string, message: string): void;
@@ -520,9 +569,9 @@ declare global {
 }
 
 /**
- * 解析查询字符串
- * @param str 转换的字符串
- * @return 转换后的对象
+ * Parse query string
+ * @param str String to convert
+ * @return Converted object
  * @example
  *
  * parse('a=1&b=2') => { a: '1', b: '2' }
@@ -537,9 +586,9 @@ declare global {
  */
 declare function parse(str: string, options?: ParseOptions): Record<string, string>;
 /**
- * 转换对象为查询字符串
- * @param obj 转换的对象
- * @return 转换后的字符串
+ * Convert object to query string
+ * @param obj Object to convert
+ * @return Converted string
  * @example
  * stringify({ a: '1', b: '2' }) => 'a=1&b=2'
  * stringify({ from: '中国' }) => 'from=%E4%B8%AD%E5%9B%BD'
@@ -547,10 +596,10 @@ declare function parse(str: string, options?: ParseOptions): Record<string, stri
  */
 declare function stringify(obj: AnyObject, options?: StringifyOptions): string;
 /**
- * url追加查询字符串
+ * Append query string to URL
  * @param url url
- * @param obj 查询字符串对象
- * @return 追加后的url
+ * @param obj Query string object
+ * @return URL with appended query string
  * @example
  * appendQueryString('https://www.baidu.com', { a: '1', b: '2' }) => 'https://www.baidu.com?a=1&b=2'
  * appendQueryString('/pages/index?id=10', { test:'23' }) => '/pages/index?id=10&test=23'
@@ -563,74 +612,171 @@ declare const qs: {
 };
 interface ParseOptions {
     /**
-     * 是否解码
+     * Whether to decode
      * @default true
      */
     decode?: boolean;
 }
 interface StringifyOptions {
     /**
-     * 是否编码
+     * Whether to encode
      * @default true
      */
     encode?: boolean;
 }
 
 /**
- * 节流函数
- * @param target 目标函数
- * @param wait 等待时间 默认 500ms
+ * Throttle function
+ * @param target Target function
+ * @param wait Wait time, default 500ms
  * @example throttle(() => console.log('hello world'), 500)
  */
 declare function throttle(target: Function, wait?: number): (...args: any[]) => any;
 
 /**
- * 校验中文、字母、数字
+ * Validates Chinese characters, letters, and digits
  */
 declare function validatorChineseOrEnglishOrNumber(value: string): boolean;
 /**
- * 校验中英文
+ * Validates Chinese characters and English letters
  */
 declare function validatorChineseOrEnglish(value: string): boolean;
 /**
- * 校验大写字母、数字、特殊字符 特殊字符包括 !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
+ * Validates uppercase letters, digits, and special characters including !"#$%&'()*+,-./:;<=>?@[\]^_`{|}~
  */
 declare function validatorUppercaseOrNumbersOrSpecial(value: string): boolean;
 /**
- * 校验大写字母、数字、_
+ * Validates uppercase letters, digits, and underscore
  */
 declare function validatorUppercaseOrNumbersOrUnderline(value: string): boolean;
 
 /**
- * 校验是否为数字
+ * Executes an asynchronous function with retry logic.
+ *
+ * This utility attempts to execute the provided async function (`fn`) up to a specified number of times (`maxAttempts`).
+ * If the function fails (throws or rejects), it will retry after a delay (`retryDelay`), optionally using exponential backoff.
+ * The operation can be cancelled early by providing an `AbortSignal`.
+ *
+ * @example
+ * // Basic usage with default settings
+ * withRetry({ fn: () => fetch('https://api.example.com/data') })
+ *
+ * @example
+ * // Advanced usage with all options
+ * const controller = new AbortController();
+ * withRetry({
+ *   fn: () => fetch('https://api.example.com/data'),
+ *   maxAttempts: 5,
+ *   retryDelay: 2000,
+ *   enableExponentialBackoff: true,
+ *   signal: controller.signal
+ * })
+ *
+ * @example
+ * // With exponential backoff (delays: 1s, 2s, 4s, 8s...)
+ * withRetry({
+ *   fn: () => apiCall(),
+ *   maxAttempts: 4,
+ *   retryDelay: 1000,
+ *   enableExponentialBackoff: true
+ * })
+ *
+ * @returns Promise that resolves with the result of the successful function execution
+ *
+ * @throws {Error} When `options` is not a plain object
+ * @throws {Error} When `fn` is not a function that returns a Promise
+ * @throws {Error} When `maxAttempts` is not a positive integer
+ * @throws {Error} When `retryDelay` is not a non-negative number
+ * @throws {Error} When `enableExponentialBackoff` is not a boolean
+ * @throws {Error} When `signal` is not an AbortSignal object
+ * @throws {Error} "Operation Cancelled" when the operation is aborted via AbortSignal
+ * @throws {any} The original error from `fn` when all retry attempts are exhausted
+ *
+ * @remarks
+ * - Uses exponential backoff when enabled: delay × 2^(attempt-1)
+ * - Supports cancellation via AbortSignal at any point during execution
+ * - Logs retry attempts for debugging purposes
+ * - Validates all input parameters and throws descriptive errors
+ * - Cleans up event listeners to prevent memory leaks
+ * - Returns immediately on first successful execution
+ * - Preserves the original error when all retries fail
+ */
+declare function withRetry<T>(options: WithRetryOptions<T>): Promise<T>;
+interface WithRetryOptions<T> {
+    /**
+     * The asynchronous function to execute with retry logic.
+     *
+     * This function should return a Promise and will be called up to `maxAttempts` times
+     * if it fails. Each call should be idempotent as it may be executed multiple times.
+     */
+    fn: () => Promise<T>;
+    /**
+     * Maximum number of attempts before failing.
+     *
+     * Must be a positive integer. If the function fails this many times,
+     * the original error from the last attempt will be thrown.
+     *
+     * @default 3
+     */
+    maxAttempts?: number;
+    /**
+     * Delay in milliseconds before each retry.
+     *
+     * Must be a non-negative number. When `enableExponentialBackoff` is true,
+     * this serves as the base delay for exponential backoff calculation.
+     *
+     * @default 1000
+     */
+    retryDelay?: number;
+    /**
+     * Whether to use exponential backoff for delays.
+     *
+     * When enabled, the actual delay will be calculated as: `retryDelay × 2^(attempt-1)`.
+     * For example, with retryDelay=1000: 1s, 2s, 4s, 8s, etc.
+     *
+     * @default false
+     */
+    enableExponentialBackoff?: boolean;
+    /**
+     * Optional AbortSignal to cancel the retry operation early.
+     *
+     * When the signal is aborted, the operation will be cancelled immediately
+     * and an "Operation Cancelled" error will be thrown. The signal is checked
+     * before each attempt and during execution via Promise.race.
+     */
+    signal?: AbortSignal;
+}
+
+/**
+ * Validates if the value contains only digits
  */
 declare function isNumberOrNumberString(val: string): boolean;
 /**
- * 校验是否为英文字母
+ * Validates if the value contains only English letters
  */
 declare function isEnglishAphabet(val: string): boolean;
 /**
- * 校验是否为大写字母
+ * Validates if the value contains only uppercase letters
  */
 declare function isUpperCase(val: string): boolean;
 /**
- * 校验是否为大写字母和数字
+ * Validates if the value contains only uppercase letters and digits
  */
 declare function isUpperCaseAndNumber(val: string): boolean;
 /**
- * 校验是否为大写字母数字和中文
+ * Validates if the value contains only uppercase letters, digits and Chinese characters
  */
 declare function isUpperCaseAndNumberAndChinese(val: string): boolean;
 /**
- * 校验是否为小写字母
+ * Validates if the value contains only lowercase letters
  */
 declare function isLowerCase(val: string): boolean;
 /**
- * 校验是否为小写字母和数字
+ * Validates if the value contains only lowercase letters and digits
  */
 declare function isLowerCaseAndNumber(val: string): boolean;
 /**
- * 校验是否为小写字母数字和中文
+ * Validates if the value contains only lowercase letters, digits and Chinese characters
  */
 declare function isLowerCaseAndNumberAndChinese(val: string): boolean;
 /**
@@ -645,145 +791,279 @@ declare function isLowerCaseAndNumberAndChinese(val: string): boolean;
 declare function isChineseString(val: string): boolean;
 
 /**
- * Validates whether the value is a float.
+ * Validates whether a string represents a valid float number.
  *
- * @example
+ * This utility checks if the input string represents a valid float,
+ * including positive and negative decimal numbers. It uses strict validation
+ * that only accepts decimal float format with at least one digit after the decimal point.
  *
+ * @example
  * isFloat('1.23') => true
- *
  * isFloat('-4.56') => true
- *
  * isFloat('0.0') => true
  *
- * isFloat('7') => false
+ * @example
+ * isFloat('7') => false (integer)
+ * isFloat('1.') => false (no decimal digits)
+ * isFloat('abc') => false (non-numeric)
+ *
+ * @returns Returns `true` if the string is a valid float, `false` otherwise
+ *
+ * @remarks
+ * - Accepts positive floats (e.g., "1.23", "999.5")
+ * - Accepts negative floats (e.g., "-1.23", "-999.5")
+ * - Accepts zero with decimal point (e.g., "0.0", "-0.0")
+ * - Rejects integers without decimal point (e.g., "7", "-7")
+ * - Rejects numbers with no digits after decimal (e.g., "1.", "-2.")
+ * - Rejects non-numeric strings (e.g., "abc", "1.2a")
  */
 declare function isFloat(val: string): boolean;
 /**
- * Validates whether the value is a positive float.
+ * Validates whether a string represents a positive float (greater than zero).
  *
- * @example
+ * This utility checks if the input string represents a positive float,
+ * which excludes zero, negative numbers, and integers. It uses strict validation
+ * that only accepts decimal numbers greater than zero.
  *
+ * @example
  * isPositiveFloat('1.23') => true
+ * isPositiveFloat('0.1') => true
  *
- * isPositiveFloat('-4.56') => false
+ * @example
+ * isPositiveFloat('-4.56') => false (negative)
+ * isPositiveFloat('0.0') => false (zero)
+ * isPositiveFloat('7') => false (integer)
  *
- * isPositiveFloat('0.0') => false
+ * @returns Returns `true` if the string is a positive float, `false` otherwise
  *
- * isPositiveFloat('7') => false
+ * @remarks
+ * - Accepts only positive floats greater than zero (e.g., "1.23", "0.5")
+ * - Rejects zero with decimal point (e.g., "0.0", "0.00")
+ * - Rejects negative floats (e.g., "-1.23", "-0.5")
+ * - Rejects integers (e.g., "7", "-7")
+ * - Rejects non-numeric strings (e.g., "abc", "1.2a")
  */
 declare function isPositiveFloat(val: string): boolean;
 /**
- * Validates whether the value is a non-negative float.
+ * Validates whether a string represents a non-negative float (zero or greater).
  *
- * @example
+ * This utility checks if the input string represents a non-negative float,
+ * which includes zero and all positive decimal numbers. It excludes negative numbers
+ * and integers without decimal points.
  *
+ * @example
  * isNonNegativeFloat('1.23') => true
+ * isNonNegativeFloat('0.0') => true
  *
- * isNonNegativeFloat('-4.56') => false
+ * @example
+ * isNonNegativeFloat('-4.56') => false (negative)
+ * isNonNegativeFloat('7') => false (integer)
+ * isNonNegativeFloat('abc') => false (non-numeric)
  *
- * isNonNegativeFloat('0.0') => true
+ * @returns Returns `true` if the string is a non-negative float, `false` otherwise
  *
- * isNonNegativeFloat('7') => false
+ * @remarks
+ * - Accepts zero with decimal point (e.g., "0.0", "0.00")
+ * - Accepts positive floats (e.g., "1.23", "999.5")
+ * - Rejects negative floats (e.g., "-1.23", "-0.5")
+ * - Rejects integers without decimal point (e.g., "7", "0")
+ * - Rejects non-numeric strings (e.g., "abc", "1.2a")
  */
 declare function isNonNegativeFloat(val: string): boolean;
 /**
- * Validates whether the value is a negative float.
+ * Validates whether a string represents a negative float (less than zero).
  *
- * @example
- *
- * isNegativeFloat('1.23') => false
+ * This utility checks if the input string represents a negative float,
+ * which excludes zero, positive numbers, and integers. It uses strict validation
+ * that only accepts decimal numbers less than zero.
  *
+ * @example
  * isNegativeFloat('-4.56') => true
+ * isNegativeFloat('-0.1') => true
  *
- * isNegativeFloat('0.0') => false
+ * @example
+ * isNegativeFloat('1.23') => false (positive)
+ * isNegativeFloat('0.0') => false (zero)
+ * isNegativeFloat('-7') => false (integer)
+ *
+ * @returns Returns `true` if the string is a negative float, `false` otherwise
  *
- * isNegativeFloat('-7') => false
+ * @remarks
+ * - Accepts only negative floats less than zero (e.g., "-1.23", "-0.5")
+ * - Rejects zero with decimal point (e.g., "0.0", "-0.0")
+ * - Rejects positive floats (e.g., "1.23", "0.5")
+ * - Rejects integers (e.g., "-7", "7")
+ * - Rejects non-numeric strings (e.g., "abc", "-1.2a")
  */
 declare function isNegativeFloat(val: string): boolean;
 /**
- * Validates whether the value is a non-positive float.
+ * Validates whether a string represents a non-positive float (zero or less).
  *
- * @example
- *
- * isNonPositiveFloat('1.23') => false
+ * This utility checks if the input string represents a non-positive float,
+ * which includes zero and all negative decimal numbers. It excludes positive numbers
+ * and integers without decimal points.
  *
+ * @example
  * isNonPositiveFloat('-4.56') => true
- *
  * isNonPositiveFloat('0.0') => true
  *
- * isNonPositiveFloat('-7') => false
+ * @example
+ * isNonPositiveFloat('1.23') => false (positive)
+ * isNonPositiveFloat('-7') => false (integer)
+ * isNonPositiveFloat('abc') => false (non-numeric)
+ *
+ * @returns Returns `true` if the string is a non-positive float, `false` otherwise
+ *
+ * @remarks
+ * - Accepts zero with decimal point (e.g., "0.0", "-0.0")
+ * - Accepts negative floats (e.g., "-1.23", "-999.5")
+ * - Rejects positive floats (e.g., "1.23", "0.5")
+ * - Rejects integers without decimal point (e.g., "-7", "0")
+ * - Rejects non-numeric strings (e.g., "abc", "-1.2a")
  */
 declare function isNonPositiveFloat(val: string): boolean;
 
 /**
- * Validates whether the value is an integer.
+ * Validates whether a string represents a valid integer number.
+ *
+ * This utility checks if the input string represents a valid integer,
+ * including positive numbers, negative numbers, and zero. It uses strict validation
+ * that only accepts decimal integer format without leading zeros (except for "0" itself).
  *
  * @example
+ * isInteger('123') => true
+ * isInteger('-456') => true
+ * isInteger('0') => true
  *
- * isInteger('546') => true
+ * @example
+ * isInteger('12.5') => false (decimal)
+ * isInteger('01') => false (leading zero)
+ * isInteger('abc') => false (non-numeric)
  *
- * isInteger('-123') => true
+ * @returns Returns `true` if the string is a valid integer, `false` otherwise
  *
- * isInteger('45.5') => false
+ * @remarks
+ * - Accepts positive integers (e.g., "1", "123", "999")
+ * - Accepts negative integers (e.g., "-1", "-123", "-999")
+ * - Accepts zero as "0"
+ * - Rejects decimal numbers (e.g., "1.5", "-2.3")
+ * - Rejects numbers with leading zeros (e.g., "01", "-02")
+ * - Rejects non-numeric strings (e.g., "abc", "12a")
  */
 declare function isInteger(val: string): boolean;
 /**
- * Validates whether the value is a positive integer.
+ * Validates whether a string represents a positive integer (greater than zero).
  *
- * @example
+ * This utility checks if the input string represents a positive integer,
+ * which excludes zero, negative numbers, and decimal values. It uses strict validation
+ * that only accepts integers starting from 1 and above.
  *
+ * @example
  * isPositiveInteger('123') => true
+ * isPositiveInteger('999') => true
  *
- * isPositiveInteger('0') => false
+ * @example
+ * isPositiveInteger('0') => false (zero)
+ * isPositiveInteger('-1') => false (negative)
+ * isPositiveInteger('1.5') => false (decimal)
  *
- * isPositiveInteger('-45') => false
+ * @returns Returns `true` if the string is a positive integer, `false` otherwise
  *
- * isPositiveInteger('45.5') => false
+ * @remarks
+ * - Accepts only positive integers greater than zero (e.g., "1", "123", "999")
+ * - Rejects zero ("0")
+ * - Rejects negative integers (e.g., "-1", "-123")
+ * - Rejects decimal numbers (e.g., "1.5", "2.0")
+ * - Rejects numbers with leading zeros (e.g., "01", "02")
+ * - Rejects non-numeric strings (e.g., "abc", "12a")
  */
 declare function isPositiveInteger(val: string): boolean;
 /**
- * Validates whether the value is a non-negative integer.
+ * Validates whether a string represents a non-negative integer (zero or greater).
  *
- * @example
+ * This utility checks if the input string represents a non-negative integer,
+ * which includes zero and all positive integers. It excludes negative numbers and decimal
+ * values, and handles the special case of negative zero.
  *
+ * @example
  * isNonNegativeInteger('456') => true
- *
  * isNonNegativeInteger('0') => true
  *
- * isNonNegativeInteger('-1') => false
+ * @example
+ * isNonNegativeInteger('-1') => false (negative)
+ * isNonNegativeInteger('1.5') => false (decimal)
+ * isNonNegativeInteger('01') => false (leading zero)
+ *
+ * @returns Returns `true` if the string is a non-negative integer, `false` otherwise
  *
- * isNonNegativeInteger('45.5') => false
+ * @remarks
+ * - Accepts zero ("0")
+ * - Accepts positive integers (e.g., "1", "123", "999")
+ * - Rejects negative integers (e.g., "-1", "-123")
+ * - Rejects decimal numbers (e.g., "1.5", "-2.3")
+ * - Rejects numbers with leading zeros (e.g., "01", "02")
+ * - Handles negative zero (-0) correctly by rejecting it
+ * - Rejects non-numeric strings (e.g., "abc", "12a")
  */
 declare function isNonNegativeInteger(val: string): boolean;
 /**
- * Validates whether the value is a negative integer.
+ * Validates whether a string represents a negative integer (less than zero).
  *
- * @example
+ * This utility checks if the input string represents a negative integer,
+ * which excludes zero, positive numbers, and decimal values. It uses strict validation
+ * that only accepts integers less than zero.
  *
+ * @example
  * isNegativeInteger('-123') => true
+ * isNegativeInteger('-1') => true
  *
- * isNegativeInteger('123') => false
+ * @example
+ * isNegativeInteger('123') => false (positive)
+ * isNegativeInteger('0') => false (zero)
+ * isNegativeInteger('-1.5') => false (decimal)
  *
- * isNegativeInteger('0') => false
+ * @returns Returns `true` if the string is a negative integer, `false` otherwise
  *
- * isNegativeInteger('-45.5') => false
+ * @remarks
+ * - Accepts only negative integers less than zero (e.g., "-1", "-123", "-999")
+ * - Rejects zero ("0")
+ * - Rejects positive integers (e.g., "1", "123")
+ * - Rejects decimal numbers (e.g., "-1.5", "2.3")
+ * - Rejects numbers with leading zeros (e.g., "-01", "-02")
+ * - Rejects non-numeric strings (e.g., "abc", "-12a")
  */
 declare function isNegativeInteger(val: string): boolean;
 /**
- * Validates whether the value is a non-positive integer.
+ * Validates whether a string represents a non-positive integer (zero or less).
  *
- * @example
+ * This utility checks if the input string represents a non-positive integer,
+ * which includes zero and all negative integers. It excludes positive numbers and decimal
+ * values, and handles the special case of negative zero.
  *
+ * @example
  * isNonPositiveInteger('-456') => true
- *
  * isNonPositiveInteger('0') => true
  *
- * isNonPositiveInteger('123') => false
+ * @example
+ * isNonPositiveInteger('123') => false (positive)
+ * isNonPositiveInteger('1.5') => false (decimal)
+ * isNonPositiveInteger('-01') => false (leading zero)
+ *
+ * @returns Returns `true` if the string is a non-positive integer, `false` otherwise
  *
- * isNonPositiveInteger('-45.5') => false
+ * @remarks
+ * - Accepts zero ("0")
+ * - Accepts negative integers (e.g., "-1", "-123", "-999")
+ * - Rejects positive integers (e.g., "1", "123")
+ * - Rejects decimal numbers (e.g., "-1.5", "2.3")
+ * - Rejects numbers with leading zeros (e.g., "-01", "-02")
+ * - Handles negative zero (-0) correctly by accepting it
+ * - Rejects non-numeric strings (e.g., "abc", "-12a")
  */
 declare function isNonPositiveInteger(val: string): boolean;
 
+declare const isStringNumber: (val: string) => boolean;
+
 /**
  * Validates whether the value is a mobile phone number.
  *
@@ -819,15 +1099,15 @@ declare function isEmail(val: string): boolean;
  */
 declare function isEmptyString(val: unknown): val is "";
 /**
- * 校验是否为合法时间格式
- * @param format 时间格式
+ * Validates if the value is a valid date string
+ * @param format Date format
  * @default 'YYYY-MM-DD HH:mm:ss'
  * @see https://day.js.org/docs/zh-CN/parse/string-format
  */
 declare function isDateString(val: string, format?: string): boolean;
 /**
- * 校验是否为二代身份证号
+ * Validates if the value is a valid Chinese ID card number
  */
 declare function isIdCard(val: string): boolean;
 
-export { type AnyObject, type ArrayItem, type Arrayable, type ParseOptions, type PlainObject, type StringNumber, type StringifyOptions, base64Decode, base64Encode, castArray, compose, composeRight, debounce, debugWarn, debugWarnInvalidTypeMessage, decimalToBinary, deepClone, deepMerge, deprecated, generateRandomArray, generateRandomColor, generateRandomDate, generateRandomEmail, generateRandomFloat, generateRandomIdCard, generateRandomMobilePhone, generateRandomStringFromSource, getRandomInt, getRandomItem, getRandomString, getRandomUrl, hasChanged, isArray, isBoolean, isChineseString, isDate, isDateString, isDef, isEmail, isEmptyString, isEnglishAphabet, isFloat, isFunction, isIdCard, isInteger, isLowerCase, isLowerCaseAndNumber, isLowerCaseAndNumberAndChinese, isMap, isMobilePhone, isNegativeFloat, isNegativeInteger, isNonNegativeFloat, isNonNegativeInteger, isNonPositiveFloat, isNonPositiveInteger, isNull, isNumber, isNumberOrNumberString, isObject, isObjectLike, isPlainObject, isPositiveFloat, isPositiveInteger, isPromise, isRegExp, isSet, isString, isSymbol, isURL, isUndef, isUndefined, isUpperCase, isUpperCaseAndNumber, isUpperCaseAndNumberAndChinese, objectToString, omit, pick, qs, throttle, throwError, throwErrorInvalidTypeMessage, toTypeString, toTypeValue, validatorChineseOrEnglish, validatorChineseOrEnglishOrNumber, validatorUppercaseOrNumbersOrSpecial, validatorUppercaseOrNumbersOrUnderline };
+export { type AnyObject, type ArrayItem, type Arrayable, type DeepMergeOptions, type ParseOptions, type PlainObject, type StringNumber, type StringifyOptions, UtilsError, type WithRetryOptions, base64Decode, base64Encode, castArray, compose, composeRight, debounce, debugWarn, debugWarnInvalidTypeMessage, decimalToBinary, deepClone, deepMerge, deprecated, generateRandomArray, generateRandomColor, generateRandomDate, generateRandomEmail, generateRandomFloat, generateRandomIdCard, generateRandomMobilePhone, generateRandomStringFromSource, getRandomInt, getRandomItem, getRandomString, getRandomUrl, hasChanged, isArray, isBoolean, isChineseString, isDate, isDateString, isDef, isEmail, isEmptyString, isEnglishAphabet, isFloat, isFunction, isIdCard, isInteger, isLowerCase, isLowerCaseAndNumber, isLowerCaseAndNumberAndChinese, isMap, isMobilePhone, isNegativeFloat, isNegativeInteger, isNonNegativeFloat, isNonNegativeInteger, isNonPositiveFloat, isNonPositiveInteger, isNull, isNumber, isNumberOrNumberString, isObject, isObjectLike, isPlainObject, isPositiveFloat, isPositiveInteger, isPromise, isRegExp, isSet, isString, isStringNumber, isSymbol, isURL, isUndef, isUndefined, isUpperCase, isUpperCaseAndNumber, isUpperCaseAndNumberAndChinese, objectToString, omit, pick, qs, throttle, throwError, throwErrorInvalidTypeMessage, toTypeString, toTypeValue, validatorChineseOrEnglish, validatorChineseOrEnglishOrNumber, validatorUppercaseOrNumbersOrSpecial, validatorUppercaseOrNumbersOrUnderline, withRetry };