@salespark/toolkit 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,500 @@
+/******************************************************
+ * ##: Unique by Key
+ * Returns unique items in an array based on a computed key
+ * @param {Array<T>} arr - The array to process
+ * @param {Function} key - Function to compute the key for uniqueness
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function uniqBy<T, K>(arr: T[], key: (v: T) => K): T[];
+/******************************************************
+ * ##: Array Chunk
+ * Splits an array into equally sized pieces
+ * @param {Array<T>} arr - The array to chunk
+ * @param {Number} size - Size of each chunk
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function chunk<T>(arr: T[], size: number): T[][];
+/******************************************************
+ * ##: Deep Array Equality
+ * Deeply compares two arrays for equality, ignoring element order and property order in nested objects
+ *
+ * Notes:
+ * - Uses JSON.stringify as the final canonical representation.
+ * - Will return false on non-serializable inputs (e.g., circular structures).
+ * - For primitives like NaN/Infinity, JSON.stringify follows JS semantics (NaN -> null).
+ * @param {Array<T>} arr1 - First array to compare
+ * @param {Array<T>} arr2 - Second array to compare
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function areArraysEqual<T = unknown>(arr1: T[], arr2: T[]): boolean;
+/**
+ * @deprecated Use `areArraysEqual` instead.
+ */
+declare const areArraysDeepEqualUnordered: typeof areArraysEqual;
+/******************************************************
+ * ##: Unique Values
+ * Removes duplicate values from an array
+ * @param {Array<T>} arr - The array to process
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function uniq<T>(arr: T[]): T[];
+/******************************************************
+ * ##: Flatten Array
+ * Flattens nested arrays into a single array (1 level deep)
+ * @param {Array<any>} arr - The array to flatten
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function flatten<T>(arr: any[]): T[];
+/******************************************************
+ * ##: Group By
+ * Groups array items by a key or function
+ * @param {Array<T>} arr - The array to group
+ * @param {Function|String} key - Key or function to group by
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function groupBy<T, K extends keyof any>(arr: T[], key: ((item: T) => K) | K): Record<string, T[]>;
+/******************************************************
+ * ##: Sort By
+ * Sorts array by a key or function
+ * @param {Array<T>} arr - The array to sort
+ * @param {Function|String} key - Key or function to sort by
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function sortBy<T>(arr: T[], key: ((item: T) => any) | keyof T): T[];
+/******************************************************
+ * ##: Array Difference
+ * Returns elements in arr1 not present in arr2
+ * @param {Array<T>} arr1 - First array
+ * @param {Array<T>} arr2 - Second array
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function difference<T>(arr1: T[], arr2: T[]): T[];
+/******************************************************
+ * ##: Array Intersection
+ * Returns elements common to both arrays
+ * @param {Array<T>} arr1 - First array
+ * @param {Array<T>} arr2 - Second array
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function intersection<T>(arr1: T[], arr2: T[]): T[];
+/******************************************************
+ * ##: Compact Array
+ * Removes falsy values from array
+ * @param {Array<T>} arr - The array to compact
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function compact<T>(arr: T[]): T[];
+/******************************************************
+ * ##: Pluck Property
+ * Extracts a property from each object in array
+ * @param {Array<T>} arr - The array of objects
+ * @param {String} key - Property name to extract
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function pluck<T, K extends keyof T>(arr: T[], key: K): Array<T[K]>;
+/******************************************************
+ * ##: Shuffle Array
+ * Shuffles array elements randomly
+ * @param {Array<T>} arr - The array to shuffle
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function shuffle<T>(arr: T[]): T[];
+/**
+ ****************************************************
+ * ##: Flattenable Value Checker
+ * Checks if a value can be flattened (array, arguments, or marked spreadable)
+ *
+ * Notes:
+ * Mirrors lodash's behavior: checks Array.isArray, arguments object, and Symbol.isConcatSpreadable.
+ * @param {unknown} value - Value to check for flattenability
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function isFlattenable(value: unknown): value is readonly unknown[];
+/**
+ ****************************************************
+ * ##: Array Push All
+ * Appends all values into array in-place (similar to lodash arrayPush)
+ * @param {Array<T>} array - Target array
+ * @param {Array<T>} values - Values to append
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function pushAll<T>(array: T[], values: readonly T[]): T[];
+/**
+ ****************************************************
+ * ##: Base Array Flatten
+ * Base flatten routine with configurable depth and predicate
+ *
+ * Notes:
+ * Allows control of depth, predicate, and strict mode. Used internally for flattening.
+ * @param {Array} array - Input array
+ * @param {Number} depth - Maximum recursion depth
+ * @param {Function} predicate - Function to determine if value is flattenable
+ * @param {Boolean} isStrict - If true, only flattenable values are kept
+ * @param {Array} result - Optional accumulator (internal)
+ * @returns {Array} New flattened array
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function flattenDepthBase<T>(array: readonly unknown[], depth: number, predicate?: (v: unknown) => boolean, isStrict?: boolean, result?: T[]): T[];
+/**
+ ****************************************************
+ * ##: Flatten Array Once
+ * Flattens array a single level deep (equivalent to lodash _.flatten)
+ *
+ * Notes:
+ * Example: flattenOnce([1, [2, [3, [4]], 5]]) => [1, 2, [3, [4]], 5]
+ * @param {Array} array - Array to flatten
+ * @returns {Array} Flattened array (1 level)
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function flattenOnce<T>(array: ReadonlyArray<T | ReadonlyArray<T>>): T[];
+/******************************************************
+ * ##: Flatten Array to Depth
+ * Flattens array up to the specified depth (friendly wrapper, default 1)
+ *
+ * Notes:
+ * Example: flattenDepth([1, [2, [3, [4]], 5]], 2) => [1, 2, 3, [4], 5]
+ * @param {Array} array - Array to flatten
+ * @param {Number} depth - Maximum depth
+ * @param {Object} options - Options: predicate, isStrict
+ * @returns {Array} Flattened array up to depth
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function flattenDepth<T = unknown>(array: readonly unknown[], depth?: number, options?: {
+    predicate?: (v: unknown) => boolean;
+    isStrict?: boolean;
+}): T[];
+
+/**
+****************************************************
+ * ##: Object Property Picker
+ * Picks specified properties from an object and returns a new object
+ * @param {Object} obj - Source object
+ * @param {Array} keys - Array of keys to pick
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function pick<T extends object, K extends keyof T>(obj: T, keys: K[]): Pick<T, K>;
+/**
+****************************************************
+ * ##: Object Property Omitter
+ * Omits specified properties from an object and returns a new object
+ * @param {Object} obj - Source object
+ * @param {Array} keys - Array of keys to omit
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function omit<T extends object, K extends keyof T>(obj: T, keys: K[]): Omit<T, K>;
+/**
+****************************************************
+ * ##: Object to Clean String
+ * Converts an object or value to a clean string without JSON braces and quotes
+ *
+ * Notes:
+ * Examples: { a: 1, b: "x" } -> "a=1_b=x", null -> "", 42 -> "42"
+ * @param {unknown} obj - Object or value to convert
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function objectToString(obj: unknown): string;
+declare function cleanObject<T = unknown>(obj: T): any;
+
+/******************************************************
+ * ##: Slugify String
+ * Converts a string to a URL-friendly slug (basic ASCII, keeps numbers and dashes)
+ * @param {String} input - String to slugify
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function slugify(input: string): string;
+/******************************************************
+ * ##: Simple String Template Filler
+ * Fills a template string with values (e.g., "Hello, {name}!")
+ * @param {String} template - Template string
+ * @param {Object} values - Key-value pairs to fill
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function fill(template: string, values: Record<string, string | number>): string;
+/******************************************************
+ * ##: Remove Diacritics
+ * Removes diacritic marks from a string using NFD normalization
+ *
+ * Notes:
+ * Examples: "ação" -> "acao", "coração" -> "coracao", "résumé" -> "resume", "naïve" -> "naive"
+ * @param {String} str - String to deburr
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function deburr(str: string): string;
+/**
+ * @deprecated Use `deburr` instead.
+ */
+declare const removeDiacritics: typeof deburr;
+/******************************************************
+ * ##: Basic String Sanitizer
+ * Sanitizes input by removing control chars, HTML/script/style/iframe blocks, dangerous URL schemes, and keeps letters/numbers/spaces/punctuation
+ *
+ * Notes:
+ * Non-string inputs return "". This is a light, generic sanitizer (not a full HTML sanitizer).
+ * @param {unknown} input - Input to sanitize
+ * @param {Number} maxLength - Optional max length for output
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function sanitize(input: unknown, maxLength?: number): string;
+/**
+ * @deprecated Use `sanitize` instead.
+ */
+declare const basicSanitize: typeof sanitize;
+
+/******************************************************
+ * ##: Clamp Number
+ * Restricts a number to be within the min and max bounds
+ * @param {Number} n - Number to clamp
+ * @param {Number} min - Minimum value
+ * @param {Number} max - Maximum value
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const clamp: (n: number, min: number, max: number) => number;
+/******************************************************
+ * ##: Fixed Decimal Rounding
+ * Rounds a number to a fixed number of decimals without floating point surprises
+ * @param {Number} n - Number to round
+ * @param {Number} decimals - Number of decimal places
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function round(n: number, decimals?: number): number;
+/******************************************************
+ * ##: Safe Integer Conversion
+ * Safely converts a value to an integer. Returns defaultValue if parsing fails or results in NaN.
+ *
+ * Notes:
+ * Examples: toInteger("42") -> 42, toInteger("abc", 10) -> 10, toInteger(undefined) -> 0, toInteger(3.9) -> 3
+ * @param {unknown} value - Value to convert
+ * @param {Number} defaultValue - Default value if parsing fails
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function toInteger(value: unknown, defaultValue?: number): number;
+/******************************************************
+ * ##: Safe Parse Int (Alias)
+ * Alias for safe integer conversion (for discoverability/backward naming)
+ * @param {unknown} value - Value to convert
+ * @param {Number} defaultValue - Default value if parsing fails
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const safeParseInt: typeof toInteger;
+/******************************************************
+ * ##: Safe Number Conversion
+ * Safely parses a value into a number with optional decimal precision
+ *
+ * Notes:
+ * Handles commas as decimal/thousands separators. Returns 0 for null/undefined/empty string or invalid parsing.
+ * Examples: toNumber("123.45") -> 123.45, toNumber("123,45") -> 123.45, toNumber("1,234.56") -> 1234.56, toNumber("abc", 2) -> 0, toNumber(42) -> 42
+ * @param {unknown} value - Value to convert
+ * @param {Number} decimals - Number of decimal places
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function toNumber(value: unknown, decimals?: number): number;
+/**
+ * @deprecated Use `toNumber` instead.
+ */
+declare const parseToNumber: typeof toNumber;
+/******************************************************
+ * ##: Random Digits Generator
+ * Generates a random string of digits with secure randomness when available
+ *
+ * Notes:
+ * Options: length (default 6), charset (default "0123456789"), noLeadingZero (if true, first char not "0"). Returns a string to preserve leading zeros. Uses Web Crypto when possible; otherwise falls back to Math.random().
+ * @param {Number} length - Number of digits
+ * @param {Object} options - Options: charset, noLeadingZero
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function randomDigits(length?: number, options?: {
+    charset?: string;
+    noLeadingZero?: boolean;
+}): string;
+/**
+ * @deprecated Use `randomDigits` instead.
+ */
+declare const otp: typeof randomDigits;
+
+/******************************************************
+ * ##: Debounce Function
+ * Returns a debounced version of a function that delays execution until after wait ms
+ * @param {Function} fn - Function to debounce
+ * @param {Number} wait - Delay in milliseconds
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function debounce<T extends (...args: any[]) => any>(fn: T, wait?: number): T;
+/******************************************************
+ * ##: Throttle Function
+ * Returns a throttled version of a function that only executes once per wait ms
+ * @param {Function} fn - Function to throttle
+ * @param {Number} wait - Delay in milliseconds
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare function throttle<T extends (...args: any[]) => any>(fn: T, wait?: number): T;
+/******************************************************
+ * ##: Nil Value Check
+ * Checks if a value is null or undefined (Type Guard)
+ * @param {unknown} value - Value to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const isNil: (value: unknown) => value is null | undefined;
+/******************************************************
+ * ##: Nil or Nil Text Check
+ * Checks if value is null/undefined or the text "null"/"undefined"
+ * @param {unknown} value - Value to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const isNilText: (value: unknown) => boolean;
+/******************************************************
+ * ##: Nil or Empty String Check
+ * Checks if value is null/undefined or an empty string ""
+ * @param {unknown} value - Value to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const isNilOrEmpty: (value: unknown) => boolean;
+/******************************************************
+ * ##: Array Nil or Empty Element Check
+ * Checks if any element in array is nil or empty (""). Returns true if input is not an array.
+ * @param {unknown} array - Array to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const hasNilOrEmpty: (array: unknown) => boolean;
+/******************************************************
+ * ##: Nil, Empty, or Zero Length Check
+ * Checks if value is nil, empty string, or has zero length (applies to arrays, strings, typed arrays, buffers)
+ * @param {unknown} value - Value to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const isNilEmptyOrZeroLen: (value: unknown) => boolean;
+/******************************************************
+ * ##: Nil or Zero Length Check
+ * Checks if value is nil or has zero length (.length === 0). Does NOT treat "" specially.
+ * @param {unknown} value - Value to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const isNilOrZeroLen: (value: unknown) => boolean;
+/******************************************************
+ * ##: Nil or NaN Check
+ * Checks if value is nil OR NaN (coercive, matches global isNaN)
+ *
+ * Notes:
+ * Uses global isNaN for parity with JS behavior (coerces strings). Example: isNaN("foo") === true.
+ * @param {unknown} value - Value to check
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const isNilOrNaN: (value: unknown) => boolean;
+/**
+ * @deprecated Use `isNil` instead.
+ */
+declare const isNullOrUndefined: (value: unknown) => value is null | undefined;
+/**
+ * @deprecated Use `isNilText` instead.
+ */
+declare const isNullOrUndefinedTextInc: (value: unknown) => boolean;
+/**
+ * @deprecated Use `isNilOrEmpty` instead.
+ */
+declare const isNullUndefinedOrEmpty: (value: unknown) => boolean;
+/**
+ * @deprecated Use `hasNilOrEmpty` instead.
+ */
+declare const isNullOrUndefinedInArray: (array: unknown) => boolean;
+/**
+ * @deprecated Use `isNilEmptyOrZeroLen` instead.
+ */
+declare const isNullOrUndefinedEmptyOrZero: (value: unknown) => boolean;
+/**
+ * @deprecated Use `isNilOrZeroLen` instead.
+ */
+declare const isNullUndefinedOrZero: (value: unknown) => boolean;
+/**
+ * @deprecated Use `isNilOrNaN` instead.
+ */
+declare const isNullOrUndefinedOrNaN: (value: unknown) => boolean;
+/******************************************************
+ * ##: Human-Readable Byte Formatter
+ * Formats bytes as human-readable text (e.g., kB, MB, KiB, MiB)
+ *
+ * Notes:
+ * SI (kB, MB, ...) uses 1000; IEC (KiB, MiB, ...) uses 1024. Negative values supported.
+ * @param {Number} bytes - Number of bytes to format
+ * @param {Boolean} si - True for metric (SI, base 1000), false for binary (IEC, base 1024)
+ * @param {Number} dp - Decimal places
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const formatBytes: (bytes: number, si?: boolean, dp?: number) => string;
+/**
+ * @deprecated Use `formatBytes` instead.
+ */
+declare const humanFileSize: (bytes: number, si?: boolean, dp?: number) => string;
+/******************************************************
+ * ##: String Similarity
+ * Returns the similarity between two strings (0..1)
+ *
+ * Notes:
+ * Similarity = (|longer|-levenshtein(longer, shorter)) / |longer|  ∈ [0, 1]. Safe for empty strings; if both empty => 1.0
+ * @param {String} s1 - First string
+ * @param {String} s2 - Second string
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const stringSimilarity: (s1: string, s2: string) => number;
+/**
+ * @deprecated Use `stringSimilarity` instead.
+ */
+declare const getStringSimilarity: (s1: string, s2: string) => number;
+/******************************************************
+ * ##: Thousand Separator Formatter
+ * Adds spaces between thousands in a number (e.g., 1234567 -> "1 234 567")
+ * @param {Number|String} value - Number or string to format
+ * @returns {String} Formatted string with spaces as thousand separators
+ * History:
+ * 21-08-2025: Created
+ ****************************************************/
+declare const addThousandsSpace: (value: number | string) => string;
+/**
+ * @deprecated Use `addThousandsSpace` instead.
+ */
+declare const addSpaceBetweenNumbers: (value: number | string) => string;
+
+/** Environment helpers (runtime-agnostic checks) */
+declare const isBrowser: boolean;
+declare const isNode: boolean;
+
+export { addSpaceBetweenNumbers, addThousandsSpace, areArraysDeepEqualUnordered, areArraysEqual, basicSanitize, chunk, clamp, cleanObject, compact, debounce, deburr, difference, fill, flatten, flattenDepth, flattenDepthBase, flattenOnce, formatBytes, getStringSimilarity, groupBy, hasNilOrEmpty, humanFileSize, intersection, isBrowser, isFlattenable, isNil, isNilEmptyOrZeroLen, isNilOrEmpty, isNilOrNaN, isNilOrZeroLen, isNilText, isNode, isNullOrUndefined, isNullOrUndefinedEmptyOrZero, isNullOrUndefinedInArray, isNullOrUndefinedOrNaN, isNullOrUndefinedTextInc, isNullUndefinedOrEmpty, isNullUndefinedOrZero, objectToString, omit, otp, parseToNumber, pick, pluck, pushAll, randomDigits, removeDiacritics, round, safeParseInt, sanitize, shuffle, slugify, sortBy, stringSimilarity, throttle, toInteger, toNumber, uniq, uniqBy };