@hairy/utils 1.45.0 → 1.46.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { clone, cloneDeep, cloneDeepWith, cloneWith, concat, debounce, find, get, groupBy, isArguments, isArray, isArrayBuffer, isArrayLike, isArrayLikeObject, isBoolean, isBuffer, isDate, isElement, isEmpty, isEqual, isEqualWith, isError, isFunction, isInteger, isMap, isMatch, isMatchWith, isNaN, isNative, isNull, isNumber, isObject, isObjectLike, isPlainObject, isRegExp as isRegexp, isSet, isString, isSymbol, isUndefined, isWeakMap, isWeakSet, join, keyBy, keys, merge, mergeWith, set, truncate, uniq, uniqBy, uniqWith, values } from 'lodash-es';
+export { chunk, clone, cloneDeep, cloneDeepWith, cloneWith, concat, debounce, find, get, groupBy, isArguments, isArray, isArrayBuffer, isArrayLike, isArrayLikeObject, isBoolean, isBuffer, isDate, isElement, isEmpty, isEqual, isEqualWith, isError, isFunction, isInteger, isMap, isMatch, isMatchWith, isNaN, isNative, isNull, isNumber, isObject, isObjectLike, isPlainObject, isRegExp as isRegexp, isSet, isString, isSymbol, isUndefined, isWeakMap, isWeakSet, join, keyBy, keys, max, maxBy, merge, mergeWith, min, minBy, omit, omitBy, once, pick, pickBy, range, set, truncate, uniq, uniqBy, uniqWith, values } from 'lodash-es';
 import _Bignumber from 'bignumber.js';
 
 interface OpenFilePickerOptions {
@@ -14,7 +14,9 @@ interface OpenFilePickerOptions {
 /**
  * Select multiple files
  */
-declare function showOpenFilePicker(option?: OpenFilePickerOptions): Promise<File[]>;
+declare function openFilePicker(option?: OpenFilePickerOptions): Promise<File[]>;
+/** @deprecated use openFilePicker */
+declare const showOpenFilePicker: typeof openFilePicker;
 interface OpenImagePickerOptions {
     /**
      * select multiple images
@@ -24,9 +26,10 @@ interface OpenImagePickerOptions {
 /**
  * Select multiple images
  */
-declare function showOpenImagePicker(options?: OpenImagePickerOptions): Promise<File[]>;
-/** @deprecated use chooseFile */
-declare const selectImages: typeof showOpenImagePicker;
+declare function openImagePicker(options?: OpenImagePickerOptions): Promise<File[]>;
+/** @deprecated use openImagePicker */
+declare const selectImages: typeof openImagePicker;
+declare const showOpenImagePicker: typeof openImagePicker;
 /**
  * Generate Blob | string file and download it
  * @param data Blob data, or string
@@ -38,7 +41,9 @@ declare function downloadBlobFile(data: Blob | string, name: string): void;
  * @param url Download link
  * @param name file name
  */
-declare function downloadNetworkFile(url: string, name?: string): void;
+declare function downloadUrlFile(url: string, name?: string): void;
+/** @deprecated use downloadUrlFile */
+declare const downloadNetworkFile: typeof downloadUrlFile;
 type ReaderType = 'readAsArrayBuffer' | 'readAsBinaryString' | 'readAsDataURL' | 'readAsText';
 /**
  * Read File file
@@ -48,6 +53,9 @@ type ReaderType = 'readAsArrayBuffer' | 'readAsBinaryString' | 'readAsDataURL' |
 declare function readFileReader<T extends ReaderType>(formType: T, file: File): Promise<T extends "readAsArrayBuffer" ? ArrayBuffer : string>;
 
 type Numeric = string | number | bigint;
+type Numberish = Numeric | {
+    toString: (...args: any[]) => string;
+} | undefined | null;
 interface DynamicObject {
     [key: string]: any;
 }
@@ -67,32 +75,9 @@ type Key = string | number | symbol;
 type BooleanLike = any;
 type Noop = (...args: any[]) => any;
 
-type DeepReadonly<T> = {
-    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
-};
-type DeepRequired<T> = {
-    [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
-};
-type DeepPartial<T> = {
-    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
-};
-type DeepReplace<T, K = unknown, V = unknown> = {
-    [P in keyof T]: K extends P ? V : DeepReplace<T[P], K, V>;
-};
-type DeepKeyof<T> = T extends object ? keyof T | DeepKeyof<T[keyof T]> : never;
-type MergeInsertions<T> = T extends object ? {
-    [K in keyof T]: MergeInsertions<T[K]>;
-} : T;
-type DeepMerge<F, S> = MergeInsertions<{
-    [K in keyof F | keyof S]: K extends keyof S & keyof F ? DeepMerge<F[K], S[K]> : K extends keyof S ? S[K] : K extends keyof F ? F[K] : never;
-}>;
-
 /**
  *  Any type that can be used where a big number is needed.
  */
-type Numberish = Numeric | {
-    toString: (...args: any[]) => string;
-} | undefined | null;
 type Awaitable<T> = T | PromiseLike<T>;
 type Arrayable<T> = T | T[];
 type Promisify<T> = Promise<Awaited<T>>;
@@ -105,7 +90,7 @@ type IfAny<T, Y, N> = 0 extends 1 & T ? Y : N;
 type IsAny<T> = IfAny<T, true, false>;
 type ConstructorType<T = void> = new (...args: any[]) => T;
 type ArgumentsType<T> = T extends ((...args: infer A) => any) ? A : never;
-declare type PromiseType<P extends PromiseLike<any>> = P extends PromiseLike<infer T> ? T : never;
+type PromiseType<P extends PromiseLike<any>> = P extends PromiseLike<infer T> ? T : never;
 type BrowserNativeObject = Date | FileList | File;
 type Option<L extends Key = 'label', V extends Key = 'value', C extends Key = 'children'> = {
     [P in L]?: string;
@@ -123,8 +108,28 @@ type PickBy<T, U> = {
 type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U;
 type Assign<T, U> = Omit<T, keyof U> & U;
 type NonUndefined<T> = T extends undefined ? never : T;
-type DeepMap<T, V> = IsAny<T> extends true ? any : T extends BrowserNativeObject ? V : T extends object ? {
-    [K in keyof T]: DeepMap<NonUndefined<T[K]>, V>;
+
+type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+type DeepRequired<T> = {
+    [P in keyof T]-?: T[P] extends object ? DeepRequired<T[P]> : T[P];
+};
+type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+type DeepReplace<T, K = unknown, V = unknown> = {
+    [P in keyof T]: K extends P ? V : DeepReplace<T[P], K, V>;
+};
+type DeepKeyof<T> = T extends object ? keyof T | DeepKeyof<T[keyof T]> : never;
+type MergeInsertions<T> = T extends object ? {
+    [K in keyof T]: MergeInsertions<T[K]>;
+} : T;
+type DeepMerge<F, S> = MergeInsertions<{
+    [K in keyof F | keyof S]: K extends keyof S & keyof F ? DeepMerge<F[K], S[K]> : K extends keyof S ? S[K] : K extends keyof F ? F[K] : never;
+}>;
+type DeepMap<T, V, ST = BrowserNativeObject> = IsAny<T> extends true ? any : T extends ST ? V : T extends object ? {
+    [K in keyof T]: DeepMap<NonUndefined<T[K]>, V, ST>;
 } : V;
 
 declare function redirectTo(url: string, target?: string): void;
@@ -322,16 +327,6 @@ declare function parseNumeric(num: Numberish, delimiters?: Delimiter[]): {
  */
 declare function formatNumeric(value?: Numberish, options?: FormatNumericOptions): string;
 
-type Dimension = Numeric | [Numeric, Numeric] | {
-    width: Numeric;
-    height: Numeric;
-};
-declare function formatUnit(value: Numeric, unit?: string): string;
-declare function formatSize(dimension: Dimension, unit?: string): {
-    width: string;
-    height: string;
-};
-
 /**
  * Intercept front and back characters, hide middle characters
  * @param value
@@ -402,19 +397,6 @@ declare function template(str: string, ...args: (string | number | bigint | unde
  */
 declare function unindent(str: TemplateStringsArray | string): string;
 
-type Typeof = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function' | 'null' | 'regexp';
-/**
- * obtain data type
- * @param target Detection object
- */
-declare function getTypeof(target: any): Typeof;
-/**
- * Detecting data types
- * @param target Detection object
- * @param type Data type
- */
-declare function isTypeof(target: any, type: Typeof): boolean;
-
 type UF$1<VT, RT> = (value: VT) => RT | PromiseLike<RT>;
 type Composed<VT, RT> = (value?: VT) => Promise<RT>;
 /**
@@ -495,52 +477,69 @@ declare namespace compose {
 }
 
 /**
- * formData to object
- * @param formData
- */
-declare function formdataToObject(formData: FormData): Record<string, string>;
-/**
- * Object to formData
- * @param object
- */
-declare function objectToFormdata(object: Record<string, string | File>): FormData;
-/**
- * Check if a value is not NaN.
- * @param value - The value to check.
- * @returns The value if it is not NaN, otherwise undefined.
- */
-declare function nonnanable<T>(value: T): T | undefined;
-/**
- * Convert a value to a number.
- * @param value - The value to convert to a number.
- * @returns The number value.
- */
-declare function numberify(value: any): number;
-/**
- * Convert a value to a string.
- * @param value - The value to convert to a string.
- * @returns The string value.
- */
-declare function stringify(value: any): string;
-/**
- * Convert a value to a numberish value.
- * @param value - The value to convert to a numberish value.
- * @returns The numberish value.
+ * A deferred promise.
+ * @param T - The type of the value.
+ * @returns The deferred promise.
+ * @example
+ * ```ts
+ * const deferred = new Deferred()
+ * deferred.resolve('value')
  */
-declare function numberish(value: Numberish): string;
-
 declare class Deferred<T> extends Promise<T> {
     resolve: (value?: T) => Deferred<T>;
     reject: (reason?: any) => Deferred<T>;
     constructor(executor?: (resolve: (value: T | PromiseLike<T>) => void, reject: (reason?: any) => void) => void);
 }
 
+/**
+ * Delay for a given number of milliseconds.
+ * @param ms - The number of milliseconds to delay.
+ * @returns A promise that resolves after the given number of milliseconds.
+ * @example
+ * ```ts
+ * delay(1000).then(() => { console.log('1 second') })
+ */
 declare function delay(ms: number): Promise<void>;
 
-declare function jsonTryParse(text: string | undefined | null): any;
+declare function tryParseJson<T = any>(text: string | undefined | null): T | undefined;
 
+/**
+ * A function that performs a loop operation with delay control.
+ * @template T - The return type of the loop function (defaults to void)
+ * @param next - A function that schedules the next iteration after a delay (in milliseconds)
+ * @returns A promise that resolves with the result of type T
+ */
 type Looper<T = void> = (next: (ms: number) => Promise<T>) => Promise<T>;
 declare function loop_return<T = void>(fn: Looper<T>): Promise<T>;
+/**
+ * Creates a cancellable loop that executes repeatedly with delays.
+ * Returns a cancel function that can be called to stop the loop.
+ * The loop will not execute further iterations after cancellation.
+ *
+ * @param fn - The loop function that receives a `next` callback to schedule the next iteration
+ * @returns A cancel function that stops the loop when called
+ *
+ * @example loop
+ * ```ts
+ * const cancel = loop(async (next) => {
+ *   console.log('tick')
+ *   await next(1000) // Wait 1 second before next iteration
+ * })
+ *
+ * // Stop the loop after 5 seconds
+ * setTimeout(cancel, 5000)
+ *```
+ *  @example loop.return
+ * ```ts
+ * const result = await loop.return(async (next) => {
+ *   if (condition) {
+ *     return 'done'
+ *   }
+ *   await next(1000)
+ * })
+ * console.log(result)
+ * ```
+ */
 declare function loop(fn: Looper<void>): Fn$1;
 declare namespace loop {
     var _a: typeof loop_return;
@@ -585,7 +584,8 @@ declare function pPipe<VT, R1, R2, R3, R4, R5, R6, R7, R8, RT>(f1: UF<VT, R1>, f
  * TypeScript, because it doesn't support **Variadic Kinds** and we explicitly
  * have to define the type of all the possible usages as method overloads.
  *
- * @example
+ * @example pipe
+ *
  * const normalizeWhiteSpaces = text => name.replace(/\s+/g, ' ').trim();
  *
  * const getInitials = pipe(
@@ -600,7 +600,7 @@ declare function pPipe<VT, R1, R2, R3, R4, R5, R6, R7, R8, RT>(f1: UF<VT, R1>, f
  * @param fn - An arity N function. Its result is the argument of next one.
  * @param fns - Functions of arity 1. Each one's result is next's argument.
  *
- * @example
+ * @example pipe.promise
  *
  * const addUnicorn = async string => `${string} Unicorn`;
  * const addRainbow = async string => `${string} Rainbow`;
@@ -626,26 +626,184 @@ declare namespace pipe {
     var promise: typeof pPipe;
 }
 
-declare function proxy<T extends object>(initObject?: T): {
-    proxy: T;
-    update: (object?: T) => void;
+type Proxyed<T extends object> = T & {
+    proxy: {
+        update: (object?: T) => void;
+        original: () => T | undefined;
+    };
 };
-declare namespace proxy {
-    var resolve: <T extends object>(target: T) => T | undefined;
-}
+/**
+ * Creates a proxy object that updates the original object when the proxy is updated.
+ * @param initObject - The initial object to proxy.
+ * @returns The proxy object.
+ *
+ * @example
+ * ```ts
+ * const obj = proxy({ name: 'John' })
+ * console.log(obj.name) // John
+ *
+ * proxy.update({ name: 'Jane' })
+ * console.log(obj.name) // Jane
+ *
+ * const obj2 = proxy()
+ *
+ * obj2.any // Error: Proxy not updated. Call object.proxy.update() to update the proxy.
+ *
+ * proxy.original(obj2) // undefined
+ * obj2.update({ name: 'John' })
+ *
+ * // get the original object
+ * proxy.original(obj2) // { name: 'John' }
+ * ```
+ */
+declare function proxy<T extends object>(initObject?: T): Proxyed<T>;
 
-declare function randomArray<T>(array: T[]): T;
+/**
+ * Get a random item from an array.
+ * @param array - The array to get a random item from.
+ * @returns The random item.
+ * @example
+ * ```ts
+ * randomItem(['a', 'b', 'c']) // 'a' | 'b' | 'c'
+ */
+declare function randomItem<T>(array: T[]): T;
+/**
+ * Get a random number between a minimum and maximum value.
+ * @param min - The minimum value.
+ * @param max - The maximum value.
+ * @returns The random number.
+ * @example
+ * ```ts
+ * randomNumber(0, 100) // 0-100
+ */
 declare function randomNumber(min: number, max: number): number;
-declare function randomString(size: number, chars?: string): string;
+/**
+ * Get a random string of a given size.
+ * @param size - The size of the string.
+ * @param chars - The characters to use in the string.
+ * @returns The random string.
+ * @example
+ * ```ts
+ * randomString() // 10 characters long
+ * randomString(20) // 20 characters long
+ * randomString(20, 'abcdefghijklmnopqrstuvwxyz') // 20 characters long
+ */
+declare function randomString(size?: number, chars?: string): string;
+
+/**
+ * formData to object
+ * @param formData
+ */
+declare function formdataToObject(formData: FormData): Record<string, string>;
+/**
+ * Object to formData
+ * @param object
+ */
+declare function objectToFormdata(object: Record<string, string | File>): FormData;
+/**
+ * Check if a value is not NaN.
+ * @param value - The value to check.
+ * @returns The value if it is not NaN, otherwise undefined.
+ */
+declare function nonnanable<T>(value: T): T | undefined;
+/**
+ * Convert a value to a number.
+ * @param value - The value to convert to a number.
+ * @returns The number value.
+ */
+declare function numberify(value: any): number;
+/**
+ * Convert a value to a string.
+ * @param value - The value to convert to a string.
+ * @returns The string value.
+ */
+declare function stringify(value: any): string;
+/**
+ * Convert a value to a numberish value.
+ * @param value - The value to convert to a numberish value.
+ * @returns The numberish value.
+ */
+declare function numberish(value: Numberish): string;
 
+/**
+ * Convert a promise to a tuple of [error, data].
+ * @param promise - The promise to convert.
+ * @param error - The error to return if the promise fails.
+ * @returns The tuple of [error, data].
+ * @example
+ * ```ts
+ * to(Promise.resolve('data')) // Promise<[null, 'data']>
+ * to(Promise.reject(new Error('error'))) // Promise<[Error, undefined]>
+ */
 declare function to<T, U = Error>(promise: Promise<T> | (() => Promise<T>), error?: object): Promise<[U, undefined] | [null, T]>;
 
-declare function toArray<T>(value?: T | T[]): T[] | undefined;
+/**
+ * Convert a value to an array.
+ * @param value - The value to convert.
+ * @param required - Whether the array is required.
+ * @returns The array.
+ * @example
+ * ```ts
+ * toArray(arrorOrItemOrUndefined) // item[] | undefined
+ * toArray(arrayOrItemOrUndefined, true) // item[]
+ */
+declare function toArray<T, R extends boolean>(value?: T | T[], required?: R): R extends true ? T[] : T[] | undefined;
 
-declare function arange(x1: number, x2?: number, stp?: number, z?: number[], z0?: number): number[];
-declare function riposte<T>(...args: [cond: boolean, value: T][]): T;
+type Dimension = Numeric | [Numeric, Numeric] | {
+    width: Numeric;
+    height: Numeric;
+};
+declare function unit(value: Numeric, unit?: string): string;
+declare function size(dimension: Dimension, unit?: string): {
+    width: string;
+    height: string;
+};
+
+/** @deprecated Use range instead */
+declare const arange: {
+    (start: number, end?: number, step?: number): number[];
+    (end: number, index: string | number, guard: object): number[];
+};
+/**
+ * Select a value based on a condition.
+ * @param args - The arguments to select from.
+ * @returns The selected value.
+ * @example
+ * ```ts
+ * select(
+ *  [condition1, value],
+ *  [condition2, value2],
+ * // default value
+ * [true, value3],
+ *  ...
+ * ) // value
+ * ```
+ */
+declare function select<T>(...args: [cond: boolean, value: T][]): T;
+/**
+ * @deprecated Use select instead
+ */
+declare const riposte: typeof select;
+/**
+ * Unwrap a value or a function that returns a value.
+ * @param value - The value or function to unwrap.
+ * @returns The unwrapped value.
+ * @example
+ * ```ts
+ * unwrap({ name: 'John' }) // { name: 'John' }
+ * unwrap(() => { return { name: 'John' } }) // { name: 'John' }
+ */
 declare function unwrap<T extends object>(value: T | (() => T)): T;
+/**
+ * Call a callback if a value is not null or undefined.
+ * @param value - The value to check.
+ * @param callback - The callback to call.
+ * @returns The result of the callback.
+ * @example
+ * ```ts
+ * whenever(value, (value) => { return 'value' }) // value
+ */
 declare function whenever<T, C extends (value: Exclude<T, null | undefined>) => any>(value: T, callback: C): ReturnType<C> | undefined;
 declare function call<T extends Fn$1<any>>(fn: T, ...args: Parameters<T>): ReturnType<T>;
 
-export { type AnyFn, type ArgumentsType, type Arrayable, type Assign, type Awaitable, BIG_INTS, Bignumber, type BooleanLike, type BrowserNativeObject, type ConstructorType, DEFAULT_BIGNUM_CONFIG, type DecimalOptions, type DeepKeyof, type DeepMap, type DeepMerge, type DeepPartial, type DeepReadonly, type DeepReplace, type DeepRequired, Deferred, type Delimiter, type Dimension, type DynamicObject, type ElementOf, type Fn$1 as Fn, type FormatGroupOptions, type FormatNumericOptions, type IfAny, type IsAny, type Key, type Looper, type MergeInsertions, type NonUndefined, type Noop, type Nullable, type NumberObject, type Numberish, type Numeric, type NumericObject, type OmitBy, type OpenFilePickerOptions, type OpenImagePickerOptions, type Option, type Overwrite, type PickBy, type PromiseFn, type PromiseType, type Promisify, type ReaderType, type StringObject, type SymbolObject, type Typeof, arange, average, bignumber, call, camelCase, capitalCase, compose, constantCase, cover, decimal, delay, dialsPhone, divide, dotCase, downloadBlobFile, downloadNetworkFile, ensurePrefix, ensureSuffix, formatNumeric, formatSize, formatUnit, formdataToObject, getTypeof, gt, gte, integer, isAndroid, isBrowser, isChrome, isEdge, isFF, isFormData, isIE, isIE11, isIE9, isIOS, isMobile, isPhantomJS, isTruthy, isTypeof, isWeex, isWindow, jsonTryParse, kebabCase, loop, lt, lte, multiply, noCase, nonnanable, noop, numberify, numberish, objectToFormdata, off, on, parseNumeric, pascalCase, pascalSnakeCase, pathCase, percentage, pipe, plus, proxy, randomArray, randomNumber, randomString, readFileReader, redirectTo, riposte, selectImages, sentenceCase, showOpenFilePicker, showOpenImagePicker, slash, snakeCase, stringify, template, to, toArray, trainCase, unindent, unwrap, whenever, zeroRemove, zerofill };
+export { type AnyFn, type ArgumentsType, type Arrayable, type Assign, type Awaitable, BIG_INTS, Bignumber, type BooleanLike, type BrowserNativeObject, type ConstructorType, DEFAULT_BIGNUM_CONFIG, type DecimalOptions, type DeepKeyof, type DeepMap, type DeepMerge, type DeepPartial, type DeepReadonly, type DeepReplace, type DeepRequired, Deferred, type Delimiter, type Dimension, type DynamicObject, type ElementOf, type Fn$1 as Fn, type FormatGroupOptions, type FormatNumericOptions, type IfAny, type IsAny, type Key, type Looper, type MergeInsertions, type NonUndefined, type Noop, type Nullable, type NumberObject, type Numberish, type Numeric, type NumericObject, type OmitBy, type OpenFilePickerOptions, type OpenImagePickerOptions, type Option, type Overwrite, type PickBy, type PromiseFn, type PromiseType, type Promisify, type Proxyed, type ReaderType, type StringObject, type SymbolObject, arange, average, bignumber, call, camelCase, capitalCase, compose, constantCase, cover, decimal, delay, dialsPhone, divide, dotCase, downloadBlobFile, downloadNetworkFile, downloadUrlFile, ensurePrefix, ensureSuffix, formatNumeric, formdataToObject, gt, gte, integer, isAndroid, isBrowser, isChrome, isEdge, isFF, isFormData, isIE, isIE11, isIE9, isIOS, isMobile, isPhantomJS, isTruthy, isWeex, isWindow, kebabCase, loop, lt, lte, multiply, noCase, nonnanable, noop, numberify, numberish, objectToFormdata, off, on, openFilePicker, openImagePicker, parseNumeric, pascalCase, pascalSnakeCase, pathCase, percentage, pipe, plus, proxy, randomItem, randomNumber, randomString, readFileReader, redirectTo, riposte, select, selectImages, sentenceCase, showOpenFilePicker, showOpenImagePicker, size, slash, snakeCase, stringify, template, to, toArray, trainCase, tryParseJson, unindent, unit, unwrap, whenever, zeroRemove, zerofill };