@etsoo/shared/lib/mjs/Utils.d.ts

TypeScript shared utilities and functions

import { DataTypes, IdType } from "./DataTypes";
import { ParsedPath } from "./types/ParsedPath";
declare global {
    interface String {
        /**
         * Add parameter to URL
         * @param this URL to add parameter
         * @param name Parameter name
         * @param value Parameter value
         * @param arrayFormat Array format to array style or not to multiple fields
         * @returns New URL
         */
        addUrlParam(this: string, name: string, value: DataTypes.Simple, arrayFormat?: boolean | string): string;
        /**
         * Add parameters to URL
         * @param this URL to add parameters
         * @param data Parameters
         * @param arrayFormat Array format to array style or not to multiple fields
         * @returns New URL
         */
        addUrlParams(this: string, data: DataTypes.SimpleObject, arrayFormat?: boolean | string): string;
        /**
         * Add parameters to URL
         * @param this URL to add parameters
         * @param params Parameters string
         * @returns New URL
         */
        addUrlParams(this: string, params: string): string;
        /**
         * Check the input string contains Chinese character or not
         * @param this Input
         * @param test Test string
         */
        containChinese(this: string): boolean;
        /**
         * Check the input string contains Korean character or not
         * @param this Input
         * @param test Test string
         */
        containKorean(this: string): boolean;
        /**
         * Check the input string contains Japanese character or not
         * @param this Input
         * @param test Test string
         */
        containJapanese(this: string): boolean;
        /**
         * Format string with parameters
         * @param this Input template
         * @param parameters Parameters to fill the template
         */
        format(this: string, ...parameters: string[]): string;
        /**
         * Format inital character to lower case or upper case
         * @param this Input string
         * @param upperCase To upper case or lower case
         */
        formatInitial(this: string, upperCase: boolean): string;
        /**
         * Hide data
         * @param this Input string
         * @param endChar End char
         */
        hideData(this: string, endChar?: string): string;
        /**
         * Hide email data
         * @param this Input email
         */
        hideEmail(this: string): string;
        /**
         * Is digits string
         * @param this Input string
         * @param minLength Minimum length
         */
        isDigits(this: string, minLength?: number): boolean;
        /**
         * Is email string
         * @param this Input string
         */
        isEmail(this: string): boolean;
        /**
         * Remove non letters (0-9, a-z, A-Z)
         * @param this Input string
         */
        removeNonLetters(this: string): string;
    }
}
/**
 * Utilities
 */
export declare namespace Utils {
    const IgnoredProperties: readonly ["changedFields", "id"];
    /**
     * Add blank item to collection
     * @param options Options
     * @param idField Id field, default is id
     * @param labelField Label field, default is label
     * @param blankLabel Blank label, default is ---
     */
    export function addBlankItem<T extends object>(options: T[], idField?: string | keyof T, labelField?: unknown, blankLabel?: string): T[];
    /**
     * Base64 chars to number
     * @param base64Chars Base64 chars
     * @returns Number
     */
    export function charsToNumber(base64Chars: string): number;
    /**
     * Correct object's property value type
     * @param input Input object
     * @param fields Fields to correct
     */
    export function correctTypes<T extends object, F extends {
        [P in keyof T]?: DataTypes.BasicNames;
    }>(input: T, fields: F): void;
    /**
     * Two values equal
     * @param v1 Value 1
     * @param v2 Value 2
     * @param strict Strict level, 0 with ==, 1 === but null equal undefined, 2 ===
     */
    export function equals(v1: unknown, v2: unknown, strict?: number): boolean;
    /**
     * Exclude specific items
     * @param items Items
     * @param field Filter field
     * @param excludedValues Excluded values
     * @returns Result
     */
    export function exclude<T extends {
        [P in D]: IdType;
    }, D extends string = "id">(items: T[], field: D, ...excludedValues: T[D][]): T[];
    /**
     * Async exclude specific items
     * @param items Items
     * @param field Filter field
     * @param excludedValues Excluded values
     * @returns Result
     */
    export function excludeAsync<T extends {
        [P in D]: IdType;
    }, D extends string = "id">(items: Promise<T[] | undefined>, field: D, ...excludedValues: T[D][]): Promise<T[] | undefined>;
    /**
     * Format inital character to lower case or upper case
     * @param input Input string
     * @param upperCase To upper case or lower case
     */
    export function formatInitial(input: string, upperCase?: boolean): string;
    /**
     * Format string with parameters
     * @param template Template with {0}, {1}, ...
     * @param parameters Parameters to fill the template
     * @returns Result
     */
    export function formatString(template: string, ...parameters: string[]): string;
    /**
     * Get data changed fields (ignored changedFields) with input data updated
     * @param input Input data
     * @param initData Initial data
     * @param ignoreFields Ignore fields, default is ['changedFields', 'id']
     * @returns
     */
    export function getDataChanges<T extends object, const I extends (keyof T & string)[] | undefined = undefined>(input: T, initData: object, ignoreFields?: I): Exclude<keyof T & string, I extends undefined ? (typeof IgnoredProperties)[number] : Exclude<I, undefined>[number]>[];
    /**
     * Get nested value from object
     * @param data Data
     * @param name Field name, support property chain like 'jsonData.logSize'
     * @returns Result
     */
    export function getNestedValue(data: object, name: string): any;
    /**
     * Get input function or value result
     * @param input Input function or value
     * @param args Arguments
     * @returns Result
     */
    export const getResult: <R, T = DataTypes.Func<R> | R>(input: T, ...args: T extends DataTypes.Func<R> ? Parameters<typeof input> : never | []) => R;
    /**
     * Get time zone
     * @param tz Default timezone, default is UTC
     * @returns Timezone
     */
    export const getTimeZone: (tz?: string) => string;
    /**
     * Check the input string contains HTML entity or not
     * @param input Input string
     * @returns Result
     */
    export function hasHtmlEntity(input: string): boolean;
    /**
     * Check the input string contains HTML tag or not
     * @param input Input string
     * @returns Result
     */
    export function hasHtmlTag(input: string): boolean;
    /**
     * Is digits string
     * @param input Input string
     * @param minLength Minimum length
     * @returns Result
     */
    export const isDigits: (input?: string, minLength?: number) => boolean;
    /**
     * Is email string
     * @param input Input string
     * @returns Result
     */
    export const isEmail: (input?: string) => boolean;
    /**
     * Join items as a string
     * @param items Items
     * @param joinPart Join string
     */
    export const joinItems: (items: (string | undefined)[], joinPart?: string) => string;
    /**
     * Merge class names
     * @param classNames Class names
     */
    export const mergeClasses: (...classNames: (string | undefined)[]) => string;
    /**
     * Create a GUID
     */
    export function newGUID(): string;
    /**
     * Number to base64 chars
     * @param num Input number
     * @returns Result
     */
    export function numberToChars(num: number): string;
    /**
     * Test two objects are equal or not
     * @param obj1 Object 1
     * @param obj2 Object 2
     * @param ignoreFields Ignored fields
     * @param strict Strict level, 0 with ==, 1 === but null equal undefined, 2 ===
     * @returns Result
     */
    export function objectEqual(obj1: object, obj2: object, ignoreFields?: string[], strict?: number): boolean;
    /**
     * Get two object's unqiue properties
     * @param obj1 Object 1
     * @param obj2 Object 2
     * @param ignoreFields Ignored fields
     * @returns Unique properties
     */
    export function objectKeys(obj1: object, obj2: object, ignoreFields?: string[]): Set<string>;
    /**
     * Get the new object's updated fields contrast to the previous object
     * @param objNew New object
     * @param objPre Previous object
     * @param ignoreFields Ignored fields
     * @param strict Strict level, 0 with ==, 1 === but null equal undefined, 2 ===
     * @returns Updated fields
     */
    export function objectUpdated(objNew: object, objPrev: object, ignoreFields?: string[], strict?: number): string[];
    /**
     * Try to parse JSON input to array
     * @param input JSON input
     * @param checkValue Type check value
     * @returns Result
     */
    export function parseJsonArray<T>(input: string, checkValue?: T): T[] | undefined;
    /**
     * Parse string (JSON) to specific type, no type conversion
     * For type conversion, please use DataTypes.convert
     * @param input Input string
     * @returns Parsed value
     */
    export function parseString<T>(input: string | undefined | null): T | undefined;
    /**
     * Parse string (JSON) to specific type, no type conversion
     * For type conversion, please use DataTypes.convert
     * @param input Input string
     * @param defaultValue Default value
     * @returns Parsed value
     */
    export function parseString<T>(input: string | undefined | null, defaultValue: T): T;
    /**
     * Remove empty values (null, undefined, '') from the input object
     * @param input Input object
     */
    export function removeEmptyValues(input: object): void;
    /**
     * Remove non letters
     * @param input Input string
     * @returns Result
     */
    export const removeNonLetters: (input?: string) => string | undefined;
    /**
     * Replace null or empty with default value
     * @param input Input string
     * @param defaultValue Default value
     * @returns Result
     */
    export const replaceNullOrEmpty: (input: string | null | undefined, defaultValue: string) => string;
    /**
     * Set source with new labels
     * @param source Source
     * @param labels Labels
     * @param reference Key reference dictionary
     */
    export const setLabels: (source: DataTypes.StringRecord, labels: DataTypes.StringRecord, reference?: Readonly<DataTypes.StringDictionary>) => void;
    /**
     * Snake name to works, 'snake_name' to 'Snake Name'
     * @param name Name text
     * @param firstOnly Only convert the first word to upper case
     */
    export const snakeNameToWord: (name: string, firstOnly?: boolean) => string;
    /**
     * Set nested value to object
     * @param data Data
     * @param name Field name, support property chain like 'jsonData.logSize'
     * @param value Value
     * @param keepNull Keep null value or not
     */
    export function setNestedValue(data: object, name: string, value: unknown, keepNull?: boolean): void;
    /**
     * Parse path similar with node.js path.parse
     * @param path Input path
     */
    export const parsePath: (path: string) => ParsedPath;
    /**
     * Sort array by favored values
     * @param items Items
     * @param favored Favored values
     * @returns Sorted array
     */
    export const sortByFavor: <T>(items: T[], favored: T[]) => T[];
    /**
     * Sort array by favored field values
     * @param items Items
     * @param field Field to sort
     * @param favored Favored field values
     * @returns Sorted array
     */
    export const sortByFieldFavor: <T, F extends keyof T>(items: T[], field: F, favored: T[F][]) => T[];
    /**
     * Trim chars
     * @param input Input string
     * @param chars Trim chars
     * @returns Result
     */
    export const trim: (input: string, ...chars: string[]) => string;
    /**
     * Trim end chars
     * @param input Input string
     * @param chars Trim chars
     * @returns Result
     */
    export const trimEnd: (input: string, ...chars: string[]) => string;
    /**
     * Trim start chars
     * @param input Input string
     * @param chars Trim chars
     * @returns Result
     */
    export const trimStart: (input: string, ...chars: string[]) => string;
    export {};
}