nhb-toolbox 4.20.27 → 4.20.30

package/CHANGELOG.md

@@ -6,6 +6,11 @@ All notable changes to the package will be documented here.
 
 ---
 
+## [4.20.30] - 2025-09-17
+
+- **Reduced** _unpacked size_ by **removing** _tsdoc comments_ from js (both `cjs` and `esm`) outputs.
+- **Updated** tsdoc for `Verbalizer/verbalizer`: **added** reference to documentation site.
+
 ## [4.20.27] - 2025-09-16
 
 - **Fixed** _issues_: (**failed to convert already past/participle regular verbs**) with `toPast()` and `toParticiple()` methods in `Verbalizer/verbalizer`.

package/dist/cjs/array/Finder.js

@@ -1,30 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Finder = void 0;
-/**
- * The `Finder` class performs optimized searching on arrays.
- * It supports binary search, fuzzy search, and smart caching with TTL.
- */
 class Finder {
     static #DEFAULT_TTL = 1000 * 60 * 5;
     #cachedResult = new Map();
     #sortedCache = new Map();
     #ttl;
     #items;
-    /**
-     * * Creates a new `Finder` instance.
-     *
-     * @param data The initial array of items or a callback returning them.
-     * @param ttl Time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.
-     */
     constructor(data, ttl = Finder.#DEFAULT_TTL) {
         this.#ttl = ttl;
         this.#items = typeof data === 'function' ? data() : data;
     }
-    /**
-     * @instance Clears cache globally or for a specific key.
-     * @param key Optional key to clear only a specific cache entry.
-     */
     clearCache(key) {
         if (key) {
             this.#cachedResult.delete(key);
@@ -33,12 +19,6 @@ class Finder {
             this.#cachedResult.clear();
         }
     }
-    /**
-     * @instance Finds all items that match the provided matcher using optional caching or fuzzy logic.
-     * @param matcher The value to match against.
-     * @param keySelector Property key or selector function.
-     * @param options Optional settings for search behavior and source list.
-     */
     findAll(matcher, keySelector, options) {
         const { fuzzy = false, needSorting = true, cacheKey = 'finder-cache', forceBinary = false, caseInsensitive = true, data, } = options ?? {};
         const source = typeof data === 'function' ? data() : (data ?? this.#items);
@@ -96,12 +76,6 @@ class Finder {
         }
         return results;
     }
-    /**
-     * @instance Finds first matching item that matches the provided matcher using optional caching or fuzzy logic.
-     * @param matcher The value to match.
-     * @param keySelector Property key or selector function.
-     * @param options Optional behavior flags and item source.
-     */
     findOne(matcher, keySelector, options) {
         const { fuzzy = false, needSorting = true, cacheKey = 'finder-cache', forceBinary = false, caseInsensitive = true, data, } = options ?? {};
         const source = typeof data === 'function' ? data() : (data ?? this.#items);
@@ -141,37 +115,14 @@ class Finder {
         }
         return result;
     }
-    /**
-     * @instance Asynchronous variant of `findAll` that accepts a promise-based data supplier.
-     * @param supplier Async function resolving the items list.
-     * @param matcher The value to match.
-     * @param keySelector Property key or selector function.
-     * @param options Optional settings for search behavior and cache.
-     */
     async findAllAsync(supplier, matcher, keySelector, options) {
         const items = await supplier();
         return this.findAll(matcher, keySelector, { ...options, data: items });
     }
-    /**
-     * @instance Asynchronous variant of `findOne`.
-     * @param supplier Async function resolving the items list.
-     * @param matcher The value to match.
-     * @param keySelector Property key or selector function.
-     * @param options Optional settings for behavior and cache.
-     */
     async findOneAsync(supplier, matcher, keySelector, options) {
         const items = await supplier();
         return this.findOne(matcher, keySelector, { ...options, data: items });
     }
-    /**
-     * @instance Performs a binary search on a sorted array using a custom key selector.
-     *
-     * @param sorted - The sorted array of items to search.
-     * @param matcher - The value to search for.
-     * @param keySelector - A function that extracts the comparable key from each item.
-     * @param caseInsensitive - Whether to compare string keys ignoring case.
-     * @returns The first matching item if found; otherwise, undefined.
-     */
     binarySearch(sorted, matcher, keySelector, caseInsensitive) {
         let min = 0, max = sorted?.length - 1;
         while (min <= max) {
@@ -187,15 +138,6 @@ class Finder {
         }
         return undefined;
     }
-    /**
-     * @instance Performs a fuzzy search on an array by matching characters in sequence.
-     *
-     * @param array - The array of items to search.
-     * @param matcher - The fuzzy search string to match against.
-     * @param keySelector - A function that extracts the key to search from each item.
-     * @param caseInsensitive - Whether to compare ignoring case for string values.
-     * @returns The first fuzzy-matching item if found; otherwise, undefined.
-     */
     fuzzySearch(array, matcher, keySelector, caseInsensitive) {
         for (const item of array) {
             const rawKey = keySelector(item);
@@ -207,12 +149,6 @@ class Finder {
         }
         return undefined;
     }
-    /**
-     * @private Checks if the characters in the target string appear in order within the source string.
-     * @param source Source string to search within.
-     * @param target Target string to match against the source string.
-     * @returns True if the target string is a fuzzy match within the source string; otherwise, false.
-     */
     #match(source, target) {
         let i = 0;
         for (const char of target) {
@@ -223,13 +159,6 @@ class Finder {
         }
         return true;
     }
-    /**
-     * @private Sorts an array and caches the result for a specified time-to-live (TTL).
-     * @param data Data to sort and cache.
-     * @param getKey Key extraction function.
-     * @param cacheKey Optional cache key for storing the result.
-     * @returns
-     */
     #sortAndCache(data, getKey, cacheKey) {
         if (cacheKey) {
             const entry = this.#sortedCache.get(cacheKey);
@@ -255,10 +184,6 @@ class Finder {
         }
         return sorted;
     }
-    /**
-     * @static @private Creates a memoized version of a key extractor.
-     * @param getKey Original key extraction function
-     */
     static #createMemoizedKeyGetter(getKey) {
         const cache = new Map();
         return (item) => {

package/dist/cjs/array/basics.js

@@ -1,31 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getLastArrayElement = exports.shuffleArray = exports.isInvalidOrEmptyArray = exports.filterArrayOfObjects = exports.flattenArray = void 0;
-/**
- * * Flattens a nested array recursively or wraps any non-array data type in an array.
- *
- * @param input - The input value, which can be a nested array or a non-array value.
- * @returns A fully flattened array of type `Flatten<T>`. If the input is not an array, it wraps it in a single-element array.
- */
 const flattenArray = (input) => {
     if (!Array.isArray(input))
         return [input];
     return input.reduce((acc, item) => {
-        // If item is an array, recursively flatten it; otherwise, add it directly.
         return acc.concat(Array.isArray(item) ? (0, exports.flattenArray)(item) : [item]);
     }, []);
 };
 exports.flattenArray = flattenArray;
-/**
- * @deprecated _Please, use `findAll` instance method from `Finder` class for **more advanced filtering and searching.**_
- *
- * * Filters an array of objects based on multiple conditions for specified keys.
- * @param array - The array of objects to filter.
- * @param conditions - An object where keys represent the property names and values represent filter conditions.
- *                     The conditions can be a function `(value: T[K]) => boolean`.
- * @returns The filtered array of objects.
- * @throws `Error` If the input is not a valid array.
- */
 const filterArrayOfObjects = (array, conditions) => {
     if (!Array.isArray(array)) {
         throw new Error('The provided input is not a valid array!');
@@ -38,12 +21,6 @@ const filterArrayOfObjects = (array, conditions) => {
     }));
 };
 exports.filterArrayOfObjects = filterArrayOfObjects;
-/**
- * * Checks if a value is an empty array or an array with only empty values.
- *
- * @param value - The value to check.
- * @returns `true` if the value is not an array, an empty array, or an array containing only `null`, `undefined`, empty objects, or empty arrays.
- */
 const isInvalidOrEmptyArray = (value) => {
     if (!Array.isArray(value))
         return true;
@@ -54,12 +31,6 @@ const isInvalidOrEmptyArray = (value) => {
         (typeof item === 'object' && Object.keys(item || {})?.length === 0));
 };
 exports.isInvalidOrEmptyArray = isInvalidOrEmptyArray;
-/**
- * * Shuffle the elements of an array.
- *
- * @param array Array to shuffle.
- * @returns Shuffled array.
- */
 const shuffleArray = (array) => {
     if ((0, exports.isInvalidOrEmptyArray)(array))
         return array;
@@ -71,12 +42,6 @@ const shuffleArray = (array) => {
     return shuffled;
 };
 exports.shuffleArray = shuffleArray;
-/**
- * * Get the last element of an array.
- *
- * @param array Array to get the last element from.
- * @returns The last element or `undefined` if the array is empty.
- */
 const getLastArrayElement = (array) => {
     return array?.length > 0 ? array[array?.length - 1] : undefined;
 };

package/dist/cjs/array/calc.js

@@ -9,19 +9,6 @@ const non_primitives_1 = require("../guards/non-primitives");
 const basics_1 = require("../number/basics");
 const helpers_1 = require("./helpers");
 const transform_1 = require("./transform");
-/**
- * * Calculates the sum of differences between two numeric fields for each item in the array.
- *
- * @param data - The array of objects to process.
- * @param first - The field name to subtract **from** (minuend), supports nested dot notation.
- * @param second - The field name to subtract (subtrahend), supports nested dot notation.
- * @param roundTo - Decimal places to round the result to. Defaults to 2.
- * @returns The total sum of differences between the two fields across all items.
- *
- * @example
- * sumFieldDifference([{ buy: 10, sell: 3 }, { buy: 8, sell: 5 }], 'buy', 'sell');
- * // => 10
- */
 function sumFieldDifference(data, first, second, roundTo = 2) {
     if (!(0, non_primitives_1.isValidArray)(data))
         return 0;
@@ -30,55 +17,18 @@ function sumFieldDifference(data, first, second, roundTo = 2) {
     }, 0);
     return (0, basics_1.roundNumber)(total, roundTo);
 }
-/**
- * * Calculates the total sum of a numeric field across all items.
- *
- * @param data - The array of objects to process.
- * @param field - The field to sum values from. Supports nested dot notation.
- * @param roundTo - Decimal places to round the result to. Defaults to 2.
- * @returns The rounded total sum.
- *
- * @example
- * sumByField([{ a: 5 }, { a: 3 }], 'a');
- * // => 8
- */
 function sumByField(data, field, roundTo = 2) {
     if (!(0, non_primitives_1.isValidArray)(data))
         return 0;
     const total = data?.reduce((acc, item) => acc + (0, helpers_1._getNumericProp)(item, field), 0);
     return (0, basics_1.roundNumber)(total, roundTo);
 }
-/**
- * * Calculates the average of a numeric field across all items.
- *
- * @param data - The array of objects to process.
- * @param field - The field to calculate the average from. Supports nested dot notation.
- * @param roundTo - Decimal places to round the result to. Defaults to 2.
- * @returns The rounded average.
- *
- * @example
- * averageByField([{ a: 4 }, { a: 6 }], 'a');
- * // => 5
- */
 function averageByField(data, field, roundTo = 2) {
     if (!(0, non_primitives_1.isValidArray)(data))
         return 0;
     const total = data?.reduce((acc, item) => acc + (0, helpers_1._getNumericProp)(item, field), 0);
     return (0, basics_1.roundNumber)(total / data.length, roundTo);
 }
-/**
- * * Groups an array of objects by a primitive field and sums another numeric field per group.
- *
- * @param data - The array of objects to group.
- * @param groupBy - The field to group by. Supports nested dot notation.
- * @param sumBy - The numeric field to sum within each group. Supports nested dot notation.
- * @param roundTo - Decimal places to round each group’s result to. Defaults to 2.
- * @returns An array of records, each with the group key and its corresponding summed value.
- *
- * @example
- * groupAndSumByField([{ type: 'A', val: 2 }, { type: 'A', val: 3 }, { type: 'B', val: 1 }], 'type', 'val');
- * // => [{ A: 5 }, { B: 1 }]
- */
 function groupAndSumByField(data, groupBy, sumBy, roundTo = 2) {
     if (!(0, non_primitives_1.isValidArray)(data))
         return [];
@@ -88,19 +38,6 @@ function groupAndSumByField(data, groupBy, sumBy, roundTo = 2) {
     }));
     return result;
 }
-/**
- * * Groups an array of objects by a primitive field and averages another numeric field per group.
- *
- * @param data - The array of objects to group.
- * @param groupBy - The field to group by. Supports nested dot notation.
- * @param averageBy - The numeric field to average within each group. Supports nested dot notation.
- * @param roundTo - Decimal places to round each group’s average to. Defaults to 2.
- * @returns An array of records, each with the group key and its corresponding average value.
- *
- * @example
- * groupAndAverageByField([{ type: 'A', val: 2 }, { type: 'A', val: 4 }, { type: 'B', val: 6 }], 'type', 'val');
- * // => [{ A: 3 }, { B: 6 }]
- */
 function groupAndAverageByField(data, groupBy, averageBy, roundTo = 2) {
     if (!(0, non_primitives_1.isValidArray)(data))
         return [];

package/dist/cjs/array/helpers.js

@@ -4,13 +4,6 @@ exports._resolveNestedKey = _resolveNestedKey;
 exports._getNumericProp = _getNumericProp;
 const non_primitives_1 = require("../guards/non-primitives");
 const utilities_1 = require("../number/utilities");
-/**
- * Safely resolves nested keys from a dot-separated string like "user.city".
- *
- * @param obj - The source object
- * @param path - The nested path string (e.g. "user.city")
- * @returns The resolved value or `undefined`
- */
 function _resolveNestedKey(obj, path) {
     if ((0, non_primitives_1.isNotEmptyObject)(obj)) {
         return path?.split('.').reduce((acc, key) => {
@@ -20,14 +13,6 @@ function _resolveNestedKey(obj, path) {
         }, obj);
     }
 }
-/**
- * Retrieves a numeric value from a nested property in dot notation.
- * Falls back to 0 if value is not a number or numeric string.
- *
- * @param obj - The source object to read from.
- * @param path - The path string like 'user.income.tax'.
- * @returns The numeric value at that path, or 0 if not valid.
- */
 function _getNumericProp(obj, path) {
     if ((0, non_primitives_1.isNotEmptyObject)(obj)) {
         const value = path?.split('.').reduce((acc, key) => {

package/dist/cjs/array/sort.js

@@ -4,34 +4,18 @@ exports.sortAnArray = sortAnArray;
 const non_primitives_1 = require("../guards/non-primitives");
 const primitives_1 = require("../guards/primitives");
 const utils_1 = require("./utils");
-/**
- * * Sorts an array of strings, numbers, booleans, or objects based on the provided options.
- *
- * - If the array contains strings, it sorts them alphabetically.
- * - If the array contains numbers, it sorts them numerically.
- * - If the array contains booleans, it sorts them by their boolean value.
- * - If the array contains objects, it sorts them by the specified field in the options `sortByField`.
- *
- * @param array - The array to sort.
- * @param options - Sorting options for objects.
- * @returns The sorted array.
- */
 function sortAnArray(array, options) {
     if (!(0, non_primitives_1.isValidArray)(array))
         return array;
-    // Check if the array contains strings
     if ((0, non_primitives_1.isArrayOfType)(array, primitives_1.isString)) {
         return [...array].sort((a, b) => options?.sortOrder === 'desc' ? (0, utils_1.naturalSort)(b, a) : (0, utils_1.naturalSort)(a, b));
     }
-    // Check if the array contains numbers
     if ((0, non_primitives_1.isArrayOfType)(array, primitives_1.isNumber)) {
         return [...array].sort((a, b) => (options?.sortOrder === 'desc' ? b - a : a - b));
     }
-    // Check if the array contains booleans
     if ((0, non_primitives_1.isArrayOfType)(array, primitives_1.isBoolean)) {
         return [...array].sort((a, b) => options?.sortOrder === 'desc' ? Number(b) - Number(a) : Number(a) - Number(b));
     }
-    // Handle array of objects
     if ((0, non_primitives_1.isArrayOfType)(array, non_primitives_1.isObject) && options && 'sortByField' in options) {
         return [...array].sort((a, b) => {
             const _getKeyValue = (obj, path) => {

package/dist/cjs/array/transform.js

@@ -12,13 +12,6 @@ const non_primitives_1 = require("../guards/non-primitives");
 const primitives_1 = require("../guards/primitives");
 const index_1 = require("../utils/index");
 const helpers_1 = require("./helpers");
-/**
- * * Converts an array of objects into a formatted array of options.
- *
- * @param data - An array of objects to convert into options.
- * @param config - The configuration object to specify the keys for the `value` (firstFieldName) and `label` (secondFieldName) fields and rename as needed.
- * @returns An array of options, where each option has `value` and `label` fields as default or as specified by user in the config options.
- */
 function createOptionsArray(data, config) {
     const { firstFieldKey, secondFieldKey, firstFieldName = 'value', secondFieldName = 'label', retainNumberValue = false, } = config || {};
     if (data && data?.length) {
@@ -36,21 +29,9 @@ function createOptionsArray(data, config) {
         return [];
     }
 }
-/**
- * * Removes duplicate values from an array, supporting deep comparison for objects and arrays.
- *
- * @param array - The array from which duplicates need to be removed.
- * @returns A new array with duplicates removed.
- */
 function removeDuplicatesFromArray(array) {
     return array?.filter((item, index, self) => index === self?.findIndex((el) => (0, index_1.isDeepEqual)(el, item)));
 }
-/**
- * * Finds duplicate values in an array, runs deep comparison for objects and arrays.
- *
- * @param array - The array in which to find duplicates.
- * @returns An array containing all duplicate entries (each one only once).
- */
 function getDuplicates(array) {
     const seen = [];
     const duplicates = [];
@@ -66,34 +47,11 @@ function getDuplicates(array) {
     }
     return duplicates;
 }
-/**
- * * Finds elements missing from one array compared to another using deep comparison.
- *
- * @param options - Configuration to specify which array to compare and direction of check.
- * @returns An array of missing elements based on the comparison direction.
- */
-/**
- * * Finds elements missing from one array compared to another using deep comparison.
- *
- * @param array1 The first array to compare.
- * @param array2 The second array to compare.
- * @param missingFrom Which direction to compare for missing values:.
- *					  - `'from-first'` → values in `array1` missing in `array2`.
- *					  - `'from-second'` → values in `array2` missing in `array1`.
- * @returns An array of missing elements based on the comparison direction.
- */
 function findMissingElements(array1, array2, missingFrom) {
     const source = (missingFrom === 'from-first' ? array1 : array2) ?? [];
     const target = (missingFrom === 'from-first' ? array2 : array1) ?? [];
     return source.filter((s) => !target?.some((t) => (0, index_1.isDeepEqual)(t, s)));
 }
-/**
- * * Splits an array into chunks of a given size.
- *
- * @param arr The array to split.
- * @param chunkSize The size of each chunk.
- * @returns An array of chunked arrays.
- */
 function splitArray(arr, chunkSize) {
     const result = [];
     for (let i = 0; i < arr?.length; i += chunkSize) {
@@ -101,22 +59,6 @@ function splitArray(arr, chunkSize) {
     }
     return result;
 }
-/**
- * * Group an array of objects by a specified key, returning only arrays of grouped objects.
- *
- * @param source - The source array of objects to group.
- * @param property - The property to group the array by. Property can be a string, number, boolean, undefined or null. Supports nested dot notation.
- *
- * @returns An array of grouped arrays. Each sub-array contains objects that share the same value for the specified property.
- *
- * @example
- * splitArrayByProperty([{ type: 'a' }, { type: 'b' }, { type: 'a' }, { type: undefined }], 'type')
- * // => [ [{ type: 'a' }, { type: 'a' }], [{ type: 'b' }], [{ type: undefined }] ]
- *
- * @notes
- * - Returns an empty array if the input is invalid or empty.
- * - Groups objects even when the group key is `undefined` or `null` (object with `null` & `undefined` property-values are grouped together).
- */
 function splitArrayByProperty(source, property) {
     if (!(0, non_primitives_1.isValidArray)(source))
         return [];
@@ -131,13 +73,6 @@ function splitArrayByProperty(source, property) {
     });
     return Object.values(grouped);
 }
-/**
- * * Rotates an array left or right by a given number of steps.
- *
- * @param arr The array to rotate.
- * @param steps The number of positions to rotate (positive: right, negative: left).
- * @returns The rotated array.
- */
 function rotateArray(arr, steps) {
     const length = arr?.length;
     if (length === 0)
@@ -145,14 +80,6 @@ function rotateArray(arr, steps) {
     const offset = ((steps % length) + length) % length;
     return arr.slice(-offset).concat(arr.slice(0, -offset));
 }
-/**
- * * Moves an element within an array from one index to another.
- *
- * @param arr The array to modify.
- * @param fromIndex The index of the element to move.
- * @param toIndex The new index for the element.
- * @returns A new array with the element moved.
- */
 function moveArrayElement(arr, fromIndex, toIndex) {
     const newArr = [...arr];
     const [item] = newArr.splice(fromIndex, 1);

package/dist/cjs/array/utils.js

@@ -1,24 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.naturalSort = naturalSort;
-/**
- * * Compare two strings using natural sorting (e.g., "file2" < "file10").
- * Optionally supports case-insensitive and locale-aware string chunk comparisons.
- *
- * @param a - The first string to compare.
- * @param b - The second string to compare.
- * @param options - Optional settings to configure comparison behavior.
- * @param options.caseInsensitive - If true, compares string chunks without case sensitivity. Defaults to `true`.
- * @param options.localeAware - If true, uses localeCompare for string chunk comparisons. Defaults to `false`.
- * @returns A negative number if `a` comes before `b`, a positive number if `a` comes after `b`, or 0 if equal.
- */
 function naturalSort(a, b, options) {
     const { caseInsensitive = true, localeAware = false } = options || {};
-    /**
-     * * Splits a string into an array of number and non-number chunks.
-     * @param str - The string to split.
-     * @returns An array of string and number parts.
-     */
     const _createChunks = (str) => {
         const chunks = [];
         let current = '';
@@ -49,16 +33,13 @@ function naturalSort(a, b, options) {
     for (let i = 0; i < Math.min(aChunks?.length, bChunks?.length); i++) {
         let aChunk = aChunks[i];
         let bChunk = bChunks[i];
-        // Normalize string chunks if case-insensitive
         if (caseInsensitive && typeof aChunk === 'string' && typeof bChunk === 'string') {
             aChunk = aChunk?.toLowerCase();
             bChunk = bChunk?.toLowerCase();
         }
-        // Compare types: number vs string
         if (typeof aChunk !== typeof bChunk) {
             return typeof aChunk === 'string' ? 1 : -1;
         }
-        // Compare same-type chunks
         if (aChunk !== bChunk) {
             if (typeof aChunk === 'number' && typeof bChunk === 'number') {
                 return aChunk - bChunk;