some-common-functions-js 1.2.0 → 2.0.0

package/index.d.ts

@@ -0,0 +1,281 @@
+/** File: ./backend/utilityFunctions/commonFunctions.js
+ * Description: Common functions to be put here.
+ * Start Date  End Date        Dev   Version  Description
+ * 2025/11/19                  ITA   1.00     Genesis.
+ * 2025/11/28                  ITA   1.01     Added function hasOnlyAll().
+ * 2025/12/22                  ITA   1.02     Improved documentation of the functions and moved in more functions.
+ * 2025/12/26                  ITA   1.03     Removed lodash dependency by re-implementing get() and set() object functions, significantly reducing this package size.
+ *                                            Added function getNextDifferent() to deal better with duplicate removal from arrays of objects.
+ * 2025/12/27                  ITA   1.04     Improved the functions getNoDuplicatesArray() and getNextDifferent() to handle more test cases.
+ *                                            Added function unset().
+ * 2025/12/28                  ITA   1.05     Improved documentation of functions to show better on the tooltip in IDEs.
+ *                                            Improved deepClone() function to handle Date objects and arrays.
+ *                                            Updated get() function to return undefined or supplied default value for paths that do not exist.
+ *                                            Updated test.js file accordingly.
+ * 2025/12/29                 ITA   1.06      Removed unnecessary use of the getPaths() function in the get() function to improve effieciency.
+ * 2026/01/01                 ITA   1.07      Changed recursive functions to iterative functions, so as to overcome stack limits when functions are used in the front-end (browsers).
+ * 2026/01/01                 ITA   1.08      Changed an additional recursive function to an iterative function.
+ * 2026/01/03                 ITA   1.09      deepClone(): Used object spread to prevent reference sharing during object assignment.
+ *                                            unset(): Replaced falsy-value evaluation with the `in` operator to correctly detect existing fields.
+ * 2026/01/10 2026/10/10      ITA   1.10      get() and unset() functions: For field existence check, replaced the use of 'in' operator with checking whether the field value of the object is undefined.
+ *                                            This prevents crashes resulting from using 'in' operator on undefined fields and objects.
+ * 2026/01/10 2026/10/10      ITA   1.11      Added more robustness in dealing with non-existent fields in get() and unset() functions.
+ * 2026/05/07 2026/05/08      ITA   1.12      Migrated to Typescript.
+ *                                            Added a robust functionality for verifying whether a variable is a plain Typescript/Javacript object.
+
+*/
+/**Return true if userName is valid
+ * @param {string} userName
+ * @returns {boolean} true if a userName is valid, otherwise false.
+ */
+export declare function isValidUserName(userName: string): boolean;
+/**Return true if a name is valid
+ * @param {string} name
+ * @returns {boolean} true if a name is valid, otherwise false.
+ */
+declare function isValidName(name: string): boolean;
+export { isValidName };
+/**Return true if userName is valid
+ * @param {string} email
+ * @returns {boolean} true if an email is valid, otherwise false.
+ */
+declare function isValidEmail(email: string): boolean;
+export { isValidEmail };
+/**Return true if userName is valid
+ * @param {string} num phone number
+ * @returns {boolean} true if phone number is valid, otherwise false.
+ */
+declare function isValidPhoneNum(num: string): boolean;
+export { isValidPhoneNum };
+/**Return true if the name of an organisation is valid
+ * @param {string} name an organisation name
+ * @returns {boolean} true if an organisation name is valid, otherwise false.
+ */
+declare function isValidOrganisationName(name: string): boolean;
+export { isValidOrganisationName };
+/**Return true if a password is valid
+ * @param {string} password
+ * @returns {boolean} true if a password is valid, otherwise false.
+ */
+declare function isValidPassword(password: string): boolean;
+export { isValidPassword };
+/** Converts the date object to a string of the form CCYY-MM-DD
+ * @param {Date} dateObj
+ * @returns {string} string of the form CCYY-MM-DD
+ */
+declare function timeStampYyyyMmDd(dateObj: Date): string;
+export { timeStampYyyyMmDd };
+/** Converts a date object to a string of the form CCYY-MM-DDThh:mm:ss.ccc, e.g. '2024-02-25T15:00:25.251'
+ * @param {Date} dateObj
+ * @returns {string} a string of the form CCYY-MM-DDThh:mm:ss.ccc.
+ */
+declare function timeStampString(dateObj: Date): string;
+export { timeStampString };
+/** Returns a numeric string with trailing zeros.
+ * E.g.
+ * addLeadingZeros(9, 4) = '0009', addLeadingZeros(123, 5) = '00123'
+ * @param {string | number} aNumber a numerical string or number.
+ * @param {number} newLength the new length of the resulting string.
+ * @returns a string of a number with the specified number of leading zeros.
+ */
+declare function addLeadingZeros(aNumber: string | number, newLength: number): string;
+export { addLeadingZeros };
+/**Convert numeric input to ZAR currency format string.
+ * @param {number | string} aNumber a number or numeric string.
+ * @returns a string of the form R 256,534.00
+*/
+declare function toZarCurrencyFormat(aNumber: number | string): string;
+export { toZarCurrencyFormat };
+/**
+ * Check if a value is a plain Typescript/JavaScript object.
+ * @param {any} value
+ * @returns {boolean}
+ */
+declare function isPlainObject(value: any): value is Record<string, any>;
+export { isPlainObject };
+/**Return a deep clone of a document object.
+ * By using deep cloning, you create a new object that is entirely separate from the original object.
+ *
+ * So that whatever you do to that clone, such as deletion of fields, does not affect the original object.
+ *
+ * NB. Works only plain Javascript/Typescript objects. Field values are not cloned if they are not plain Javascript objects, but are returned as is.
+ * @template T
+ * @param {T} obj a plain Typescript/Javascript object.
+ * @returns a Typescript/Javascript object that is separate from the original object.
+ * @note For a full deep clone of Arrays, Maps, and Sets (that throws on functions), consider using the native {@link structuredClone}.
+ */
+declare function deepClone<T extends object>(obj: T): T;
+export { deepClone };
+/**
+ * Get the paths (fields) of the plain Javascript object.
+ * @template T
+ * @param {T} anObject  a plain Typescript/Javascript object.
+ * @returns a sorted string array of paths.
+ */
+declare function getPaths<T extends object>(anObject: T): string[];
+export { getPaths };
+/** Return an object with sorted fields,  ordered by field name ascending.
+ *
+ * The returned object is independent of the source object.
+ *
+ * NB. For comparison of objects, please see objCompare() function.
+ * @template T
+ * @param {T} pObject plain Typescript/Javascript object.
+ * @returns {T} an object with fields sorted in ascending order of field names.
+*/
+declare function getSortedObject<T extends object>(pObject: T): T;
+export { getSortedObject };
+/** Get the value of a field specified by the path from an object.
+ * @template T
+ * @param {T} anObject a Typescript/Javascript object.
+ * @param {string} path a path specifying the field whose value is to be obtained.
+ * @param {any} [defaultVal=undefined] a default value to return if the path does not exist on the object.
+ * @returns {U|undefined} the value of the field specified by the path, otherwise a default value if supplied.
+ */
+declare function get<T extends object, U extends any>(anObject: T, path: string, defaultVal?: U | undefined): U | undefined;
+export { get };
+/** Set the value of a field specified by the path on an object.
+ * @template T, U
+ * @param {object} anObject a Typescript/Javascript object.
+ * @param {string} path a path specifying the field whose value is to be set.
+ * @param {U} value the value to set.
+ */
+declare function set<T extends object, U>(anObject: T, path: string, value: U): void;
+export { set };
+/** Unset the value of a field specified by the path on an object.
+ * @template T
+ * @param {T} anObject a Typescript/Javascript object.
+ * @param {string} path a path specifying the field whose value is to be set.
+ */
+declare function unset<T extends object>(anObject: T, path: string): void;
+export { unset };
+/**
+ * Determine whether an object contains only 1, some or all of the specified fields, and not any other fields.
+ * @template T
+ * @param {T} anObject a Javascript object.
+ * @param  {...string[]} fields one or more field names.
+ * @returns boolean true or false.
+ */
+declare function hasOnly<T extends object>(anObject: T, ...fields: string[]): boolean;
+export { hasOnly };
+/**
+ * Determine whether an object contains all of the specified fields in addition to other fields.
+ * @template T
+ * @param {T} anObject a Javascript object.
+ * @param  {...string[]} fields one or field names.
+ * @returns boolean true or false.
+ */
+declare function hasAll<T extends object>(anObject: T, ...fields: string[]): boolean;
+export { hasAll };
+/**
+ * Determine whether an object contains only all of the specified fields. Nothing more, nothing less.
+ * @param {T} anObject a Javascript object.
+ * @param  {...string[]} fields one or field names.
+ * @returns boolean true or false.
+ */
+declare function hasOnlyAll<T extends object>(anObject: T, ...fields: string[]): boolean;
+export { hasOnlyAll };
+/**Binary Search the sorted primitive data array for a value and return the index.
+ *
+ * ArraySortDir specifies the direction in which the array is sorted (desc or asc).
+ *
+ * If the array contains the value searched for, then the index returned is the location of this value on the array,
+ * otherwise, the index is of closest value in the array that is before or after the search value in terms of sort order.
+ *
+ * This function can be used also in cases where values are to be inserted into the array while maintaining sort order.
+ * @template T
+ * @param {Array<T>} anArray an array of primitve type. All element must be the same type.
+ * @param {T} searchVal search value
+ * @param {number} [startFrom=0] index from which to start. Default: 0.
+ * @param {'asc' | 'desc'} [arraySortDir='asc'] sort direction. Must be 'asc' or 'desc'. Default: 'asc'
+ * @returns {number} an index. -1 mean value not found.
+ */
+declare function binarySearch<T>(anArray: T[], searchVal: T, startFrom?: number, arraySortDir?: 'asc' | 'desc'): number;
+export { binarySearch };
+/** Compare two values of the same primitive type, according to the sort direction.
+ * May be used with dates, numbers, booleans and strings. For other types, the result is unpredictable.
+ *
+ * A return value of -1 means that value1 is before value2 in terms of sort order.
+ *
+ * A return value of 1 means that value1 is after value2 in terms of sort order.
+ *
+ * A return value of 0 means that value1 is equal to value2.
+ * @template T
+ * @param {T} value1
+ * @param {T} value2
+ * @param {'asc' | 'desc'} [sortDir='asc'] sort direction. Must be 'asc' or 'desc'. Default: 'asc'
+ * @returns {number}  -1, 0 or 1
+*/
+declare function compare<T>(value1: T, value2: T, sortDir?: 'asc' | 'desc'): number;
+export { compare };
+/**Binary Search the sorted (ascending or descending order) array of plain Typescript/Javascript objects for a value and return the index.
+ *
+ * The assumption is that the array is sorted in order of 1 or more sort fields,
+ *
+ * Examples of sort fields: 'lastName asc', 'firstName', 'address.province asc', 'address.townOrCity asc'.
+ *
+ * If the array contains the object with values searched for, then the index returned is the location of this value in the array, otherwise,
+ * the index is of the closest value in the array that is before or after the searchObj value.
+ * Return -1 for an empty array.
+ * Assumed field data types are numbers, strings, booleans and dates.
+ * This function is to be used also in cases where objects are to be inserted into the array while maintaining sort order.
+ * @template T
+ * @param {Array<T>} objArray an array of Javascript objects.
+ * @param {T} searchObj an object to search for.
+ * @param {number} [startFrom=0] index from which to start searching.
+ * @param {...string[]} sortFields one or more search fields.
+ * @returns {number} an index.
+ */
+declare function binarySearchObj<T extends object>(objArray: T[], searchObj: T, startFrom?: number, ...sortFields: string[]): number;
+export { binarySearchObj };
+/**Get the index of the first element in an object array that is different from the target element
+ * according to the comparison fields.
+ * @template T
+ * @param {Array<T>} objArray an array of objects
+ * @param {T} targetObj target object
+ * @param {number} startFrom index from which to start searching
+ * @param {...string[]} comparisonFields the fields sort order of the array. e.g. 'score desc', 'numGames asc'.
+ * @returns index of the next different object.
+ */
+declare function getNextDifferent<T extends object>(objArray: T[], targetObj: T, startFrom: number, ...comparisonFields: string[]): number;
+export { getNextDifferent };
+/**Create an array with duplicates eliminated, according to certain fields. Taking only the first or last object from each duplicate set.
+ *
+ * If firstOfDuplicates === true, then the first element in each set of duplicates is taken.
+ *
+ * if firstOfDuplicates === false, then the last element is taken from each set of duplicates.
+ *
+ * Assumed comparison field data types are Boolean, Number, String, Date.
+ *
+ * The array must be sorted according to the comparison fields before calling this function.
+ * The value of the comparison field must include both the field name and sort direction.
+ * Sort direction assumed to be "asc" if not provided.
+ * Examples of comparison fields: "firstName", "lastName desc", "address.province asc", "address.townOrCity".
+ * @template T
+ * @param {Array<T>} objArray an input array of objects
+ * @param {boolean} firstOfDuplicates specify whether to take the first or last object in each a duplicate set.
+ * @param {...string[]} comparisonFields comparison fieds plus sort order.
+ * @returns {Array<T>} an array with no duplicates.
+ */
+declare function getObjArrayWithNoDuplicates<T extends object>(objArray: T[], firstOfDuplicates: boolean, ...comparisonFields: string[]): T[];
+export { getObjArrayWithNoDuplicates };
+/**Compare 2 objects according to the comparison fields, and return the result of:
+ *
+ * -1 if obj1 is before obj2, 1 if obj1 is after obj2, 0 if obj1 is equal to obj2.
+ *
+ * Each each of the comparisonFields must be of the form 'fieldName sortDirection' or 'fieldName'.
+ *
+ * Sort directions: 'asc', 'desc'.
+ *
+ * Field/sort-direction examples: 'lastName desc', 'firstName', 'firstName asc', 'address.provinceName asc'.
+ *
+ * If sort direction is not provided, then it is assumed to be ascending.
+ * @template T
+ * @param {T} obj1 first object to compare
+ * @param {T} obj2 second object to compare
+ * @param  {...string[]} comparisonFields one or more comparison fields plus sort order.
+ * @returns {number} comparison result: -1, 0 or 1.
+*/
+declare function objCompare<T extends object>(obj1: T, obj2: T, ...comparisonFields: string[]): number;
+export { objCompare };
+//# sourceMappingURL=index.d.ts.map