General helper utilities used across the library.
Methods
# static dataMapper(data, mapper, propsopt) → {Array.<T>}
This function transforms an array of objects by applying mapping rules to each item using the itemMapper function. It processes each element in the data array and creates new mapped objects based on the mapper configuration. The function includes validation to ensure meaningful data: if a mapped item contains only null/undefined values, it preserves the original item instead. This prevents data loss during transformation. Returns an empty array if the input data is null, undefined, or empty.
Maps an array of data objects using a provided mapper object.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
data |
Array.<T>
|
The array of data objects to be mapped |
|
mapper |
KeyValue
|
An object that defines the mapping rules |
|
props |
KeyValue
|
<optional> |
Additional properties to be included in the mapped items |
The array of mapped items. If an item in the original array does not have any non-null values after mapping, the original item is returned instead
Array.<T>
# static filterString(original, value, containopt) → {string}
This function removes or retains strings based on whether they include the specified substring. If the input is a single string, it is split into an array using spaces as delimiters before filtering.
Filters out strings containing or not containing a specific substring from an array or space-separated string.
Parameters:
| Name | Type | Attributes | Default | Description |
|---|---|---|---|---|
original |
string
|
Array.<string>
|
The input string or array of strings to filter. |
||
value |
string
|
The substring to filter by. |
||
contain |
boolean
|
<optional> |
true | Determines the filtering behavior. If true, retains strings containing the substring; otherwise, removes them. |
A string that contains or excludes the specified substring based on the contain parameter.
string
# static formatDate(date, localeopt) → {Date|string}
This function converts a date value into a formatted string according to a specified or system locale. It accepts multiple input formats (Date objects, timestamps, or date strings) and returns a consistently formatted date string in DD/MM/YYYY format. If the input date is invalid, the function returns the original input as a string. The function automatically uses the system locale if none is provided and handles string format conversions by replacing forward slashes with hyphens for proper Date parsing.
Formats a date into a localized string representation.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
date |
string
|
Date
|
number
|
The date to format. Can be a Date object, a timestamp number, or a date string |
|
locale |
string
|
<optional> |
The locale to use for formatting. If not provided, the system's locale will be used |
A formatted date string in the format DD/MM/YYYY according to the specified locale, or the original input as a string if the date is invalid
Date
|
string
# static isValidDate(date) → {boolean}
This validation function determines whether a given value represents a valid date. It handles multiple input types including Date objects, timestamp numbers, and date strings. For string inputs, it supports ISO 8601 format (YYYY-MM-DD) with or without time components. The function performs comprehensive validation including regex pattern matching and Date object creation to ensure the date is not only parseable but also represents a real date.
Checks if a value is a valid Date object.
Parameters:
| Name | Type | Description |
|---|---|---|
date |
string
|
Date
|
number
|
The value to check. Can be a Date object, a timestamp number, or a date string |
Returns true if the value is a valid Date object (not NaN), otherwise false
boolean
# static itemMapper(item, mapper, propsopt) → {KeyValue}
This function transforms a source object into a new object based on mapping rules defined in the mapper parameter. It supports dot notation for nested property access (e.g., 'user.name.first') and handles various data types including strings and complex objects. For date values, it automatically formats them using the formatDate function. The function also allows merging additional properties into the result. When a mapped value is null or undefined, it uses the original mapper value as a fallback.
Maps an item object using a provided mapper object and optional additional properties.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
item |
KeyValue
|
The source object to be mapped |
|
mapper |
KeyValue
|
An object that defines the mapping rules. Keys represent the new property names, and values represent the path to the corresponding values in the source object |
|
props |
KeyValue
|
<optional> |
Optional additional properties to be included in the mapped object |
A new object with properties mapped according to the mapper object and including any additional properties
KeyValue
# static parseToValidDate(date) → {Date|null}
This function provides robust date parsing functionality that handles the specific format "DD/MM/YYYY HH:MM:SS:MS". It first validates the input date, and if already valid, returns it as-is. For string inputs, it parses the date and time components separately, extracts numeric values, and constructs a new Date object. The function includes validation to ensure the resulting Date object is valid and logs a warning if parsing fails. Returns null for invalid or unsupported date formats.
Attempts to parse a date string, Date object, or number into a valid Date object.
Parameters:
| Name | Type | Description |
|---|---|---|
date |
string
|
Date
|
number
|
The date to parse. Can be a Date object, a timestamp number, or a date string in the format "DD/MM/YYYY HH:MM:SS:MS" |
A valid Date object if parsing is successful, or null if the date is invalid or doesn't match the expected format
Date
|
null
# static stringToBoolean(prop) → {boolean}
This utility function handles conversion of string-based boolean values ('true', 'false') to actual boolean types. It performs case-insensitive string comparison and returns the corresponding boolean value. This is particularly useful when parsing configuration values, URL parameters, or form inputs that may come as strings but need to be used as booleans.
Converts a string representation of a boolean or a boolean value to a boolean type.
Parameters:
| Name | Type | Description |
|---|---|---|
prop |
'true'
|
'false'
|
boolean
|
The value to convert. Can be the string 'true', 'false', or a boolean |
The boolean representation of the input value. Returns true if the input is the string 'true' or boolean true, false otherwise
boolean