@wikicasa-dev/node-common 4.7.12 → 5.0.0

package/dist/src/common.js

@@ -10,6 +10,14 @@ export class CustomError extends Error {
         this.critical = critical;
     }
 }
+/**
+ * Execute promise factories in sequential batches, resolving groups of `step` at a time.
+ *
+ * @param promises - Array of async factory functions
+ * @param step - Number of promises to run concurrently per batch
+ * @param exit - Reserved for future use
+ * @returns Flat array of all results
+ */
 export function sequentially(promises, step = 1, exit = false) {
     return new Promise(resolve => {
         let results = [];
@@ -34,6 +42,14 @@ export function sequentially(promises, step = 1, exit = false) {
         });
     });
 }
+/**
+ * Execute promise factories with bounded concurrency, optionally halting on error.
+ *
+ * @param promises - Array of async factory functions
+ * @param concurrent - Maximum number of concurrent executions
+ * @param stopIfError - If true, reject and stop the pool on the first error
+ * @returns Array of results in corresponding order
+ */
 export function pool(promises, concurrent, stopIfError = true) {
     return new Promise((resolve, reject) => {
         PromisePool.for(promises)
@@ -50,6 +66,13 @@ export function pool(promises, concurrent, stopIfError = true) {
             .catch((poolResult) => reject(poolResult.errors));
     });
 }
+/**
+ * Try each async factory in order and return the first truthy result; throw if none succeeds.
+ *
+ * @param fns - Array of async factory functions to try sequentially
+ * @returns First truthy resolved value
+ * @throws {string} When no factory returns a truthy value
+ */
 export async function promisesFirst(fns) {
     for await (const f of fns) {
         try {
@@ -59,12 +82,17 @@ export async function promisesFirst(fns) {
             }
         }
         catch (e) {
-            //console.error(e);
-            //
+            // ignored: expected failure for sequential first-match pattern
         }
     }
     throw "No promises resolve";
 }
+/**
+ * Read and decompress a Brotli-compressed JSON cache file from disk.
+ *
+ * @param path - Base file path (`.br` extension is appended automatically)
+ * @returns Parsed JSON data or null if the file is missing or corrupted
+ */
 export function readCache(path) {
     const brotliPath = `${path}.br`;
     if (!fs.existsSync(brotliPath))
@@ -74,19 +102,34 @@ export function readCache(path) {
         data = JSON.parse(brotliDecompressSync(fs.readFileSync(brotliPath)).toString());
     }
     catch (e) {
+        // ignored: corrupted cache returns null by design
         data = null;
     }
     return data;
 }
+/**
+ * Serialise data as JSON, compress with Brotli, and write to disk.
+ *
+ * @param path - Base file path (`.br` extension is appended automatically)
+ * @param data - Data to serialise and cache
+ */
 export function writeCache(path, data) {
     const brotliPath = `${path}.br`;
     try {
         fs.writeFileSync(brotliPath, brotliCompressSync(JSON.stringify(data)), "binary");
     }
     catch (e) {
-        console.error("Can't pack data to file");
+        Console.error("Cache write to file failed", { path, error: e });
     }
 }
+/**
+ * Read and parse a JSON file from disk.
+ *
+ * @param path - File path
+ * @param strict - If true, throw when the file does not exist
+ * @returns Parsed object or null on failure
+ * @throws {Error} When strict is true and the file is missing
+ */
 export function readJson(path, strict = false) {
     if (!fs.existsSync(path) && strict)
         throw new Error(`File ${path} not found`);
@@ -97,10 +140,20 @@ export function readJson(path, strict = false) {
         json = JSON.parse(fs.readFileSync(path, "utf8"));
     }
     catch (e) {
+        // ignored: invalid JSON returns null by design
         json = null;
     }
     return json;
 }
+/**
+ * Read and parse a CSV file into an array of row objects.
+ *
+ * @param path - File path
+ * @param delimiter - Column delimiter character
+ * @param strict - If true, throw when the file does not exist
+ * @returns Array of row objects or null on failure
+ * @throws {Error} When strict is true and the file is missing
+ */
 export function readCSV(path, delimiter = ",", strict = false) {
     if (!fs.existsSync(path) && strict)
         throw new Error(`File ${path} not found`);
@@ -115,10 +168,18 @@ export function readCSV(path, delimiter = ",", strict = false) {
         });
     }
     catch (e) {
+        // ignored: invalid CSV returns null by design
         csv = null;
     }
     return csv;
 }
+/**
+ * Group array elements into a Map keyed by the result of a getter function.
+ *
+ * @param list - Source array
+ * @param keyGetter - Function that extracts the grouping key from each item
+ * @returns Map of key to array of matching items
+ */
 export function groupBy(list, keyGetter) {
     const map = new Map();
     for (const item of list ?? []) {
@@ -133,6 +194,12 @@ export function groupBy(list, keyGetter) {
     }
     return map;
 }
+/**
+ * Pause execution for a given number of milliseconds, optionally logging a countdown spinner.
+ *
+ * @param ms - Duration in milliseconds
+ * @param feedback - If true, display a countdown spinner in the console
+ */
 export function sleep(ms, feedback = false) {
     return new Promise(resolve => {
         const t = performance.now();
@@ -140,19 +207,25 @@ export function sleep(ms, feedback = false) {
         if (feedback)
             setInterval(function () {
                 const left = (ms - (performance.now() - t)) / 1000;
-                Console.log(`Time left: ${Math.round(left)}s`, { spinner: true });
+                Console.log("Time left", { seconds: Math.round(left) }, { spinner: true });
             }, 1000);
     });
 }
+/**
+ * Deduplicate an array using Set, preserving insertion order.
+ *
+ * @param array - Source array
+ * @returns New array without duplicates, or undefined if empty/null
+ */
 export function unique(array) {
     if (!array || !array.length)
         return;
     return Array.from(new Set(array));
 }
 /**
- * Verifica se una stringa è un JSON valido
- * @param str stringa da verificare
- * @returns boolean
+ * Checks whether a string is valid JSON
+ * @param str - String to validate
+ * @returns Whether the string is valid JSON
  */
 export function isValidJSON(str) {
     if (typeof str !== "string")

package/dist/src/common.js.map

@@ -1 +1 @@
-{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/common.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"common.js","sourceRoot":"","sources":["../../src/common.ts"],"names":[],"mappings":"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"}

package/dist/src/utils.d.ts

@@ -1,68 +1,207 @@
 import hash from "object-hash";
+/**
+ * Rotate an array left by n positions, mutating it in place.
+ *
+ * @param arr - Array to rotate
+ * @param n - Number of positions to shift
+ * @returns The mutated array
+ */
 export declare function arrayRotate<T>(arr: Array<T>, n: any): Array<T>;
+/**
+ * Strip all non-ASCII characters after normalising typographic quotes.
+ *
+ * @param str - Input string
+ * @returns ASCII-only string
+ */
 export declare function cleanASCII(str: string): string;
+/**
+ * Replace typographic apostrophes and smart quotes with their ASCII equivalents.
+ *
+ * @param str - Input string
+ * @returns Normalised string
+ */
 export declare function cleanUpSpecialChars(str: string): string;
+/**
+ * Normalise special characters and strip all non-word characters.
+ *
+ * @param str - Input string
+ * @returns Alphanumeric-only string
+ */
 export declare function normalizeString(str: string): string;
+/**
+ * Collapse consecutive whitespace/tabs to a single space and consecutive newlines to one.
+ *
+ * @param str - Input string
+ * @returns Trimmed and collapsed string
+ */
 export declare function trimAll(str: string): string;
+/**
+ * Replace accented Latin characters with their unaccented ASCII equivalents.
+ *
+ * @param str - Input string
+ * @returns Transliterated string
+ */
 export declare function cleanUpSpecialChars2(str: string): string;
+/**
+ * Capitalise the first letter of each word and lowercase the rest.
+ *
+ * @param str - Input string
+ * @returns Title-cased string
+ */
 export declare function capitalizeWords(str: string): string;
+/**
+ * Uppercase only the first character of a string, leaving the rest unchanged.
+ *
+ * @param str - Input string
+ * @returns String with first letter capitalised, or undefined if empty
+ */
 export declare function capitalizeFirstLetter(str: string): string | undefined;
+/**
+ * Sort an array of objects in ascending order by a given property (in place).
+ *
+ * @param arr - Array to sort
+ * @param prop - Property key to sort by
+ * @returns The sorted array
+ */
 export declare function orderBy<T extends object>(arr: Array<T>, prop: any): Array<T>;
+/**
+ * Zero-pad a number to a fixed width.
+ *
+ * @param number - Value to pad
+ * @param digits - Desired string length
+ * @returns Zero-padded string
+ */
 export declare function pan(number: number, digits: number): string;
+/**
+ * Deduplicate an array using a custom equality comparator.
+ *
+ * @param array - Source array
+ * @param compareFn - Returns true when two elements are considered equal
+ * @returns New array with duplicates removed
+ */
 export declare function uniqWith<T>(array: Array<T>, compareFn: any): Array<T>;
+/**
+ * Return the first n elements of an array without mutating the original.
+ *
+ * @param array - Source array
+ * @param n - Maximum number of elements to take
+ * @returns New array of up to n elements
+ */
 export declare function pop<T>(array: Array<T>, n: number): Array<T>;
+/**
+ * Split an array into sub-arrays of a given size.
+ *
+ * @param array - Source array
+ * @param chunkSize - Maximum elements per chunk
+ * @returns Array of chunks
+ */
 export declare function splitChunks<T>(array: Array<T>, chunkSize: number): Array<T>;
+/**
+ * Remove the first element matching a predicate by nullifying it, then filter nulls.
+ *
+ * @param list - Source array (mutated)
+ * @param fn - Predicate identifying the element to remove
+ * @returns Filtered array without the matched element
+ */
 export declare function newpopList<T>(list: Array<T>, fn?: (a: T) => boolean): Array<T>;
+/**
+ * Extract elements common to both lists (intersection), mutating both lists to remove matched items.
+ *
+ * @param list1 - First list (mutated: matched items nullified)
+ * @param list2 - Second list (mutated: matched items nullified)
+ * @param fn - Optional hash function for comparison; defaults to object-hash
+ * @returns Array of elements found in both lists
+ */
 export declare function popList<T extends hash.NotUndefined>(list1: Array<T>, list2: Array<T>, fn?: (a: T) => string): Array<T>;
+/**
+ * Compute the symmetric difference between two lists (elements unique to either side).
+ *
+ * @param list1 - First list
+ * @param list2 - Second list
+ * @param fn - Optional hash function for comparison; defaults to object-hash
+ * @returns Elements that appear in only one of the two lists
+ */
 export declare function diffList<T extends hash.NotUndefined>(list1: Array<T>, list2: Array<T>, fn?: any): Array<T>;
+/**
+ * Truncate a number to a fixed number of decimal places (no rounding).
+ *
+ * @param num - Value to truncate
+ * @param digits - Number of decimal places to keep
+ * @returns Truncated number
+ */
 export declare function truncator(num: any, digits: any): number;
+/**
+ * Parse a localised number string by stripping leading non-digits and thousand separators.
+ *
+ * @param num - Localised number string (e.g. "EUR 1.200")
+ * @param thousand - Thousand separator character to remove
+ * @returns Parsed float
+ */
 export declare function parseNumber(num: string, thousand?: string): number;
+/**
+ * Pick a uniformly random element from an array.
+ *
+ * @param arr - Source array
+ * @returns Random element
+ */
 export declare function getRandom<T>(arr: Array<T>): T;
+/**
+ * Randomly shuffle an array in place using the Fisher-Yates algorithm.
+ *
+ * @param array - Array to shuffle (mutated)
+ * @returns The shuffled array
+ */
 export declare function shuffleArray<T>(array: T[]): T[];
+/**
+ * Extract the first number (including thousand separators and decimals) from a string.
+ *
+ * @param str - Input string containing a number
+ * @returns First matched number as a string, or undefined
+ */
 export declare function extractNumbers(str: string): string | undefined;
 /**
- * Converte una stringa in un numero, rimuovendo tutti i caratteri non numerici
- * @param str - La stringa da convertire
- * @param integerIfAmbiguous - Se true (default), il numero viene convertito in un numero intero se l'input è ambiguo
- * @returns Il numero convertito o undefined se la stringa non è valida
+ * Parses a number from a string, stripping all non-numeric characters
+ * @param str - The string to parse
+ * @param integerIfAmbiguous - If true (default), ambiguous inputs are parsed as integers
+ * @returns The parsed number, or undefined if the string is invalid
  */
 export declare function parseNumberFromString(str: string, integerIfAmbiguous?: boolean): number | undefined;
 /**
- * @deprecated
- * Converte una stringa in un numero, rimuovendo tutti i caratteri non numerici
- * @param str - La stringa da convertire
- * @returns Il numero convertito o undefined se la stringa non è valida
+ * @deprecated Use {@link parseNumberFromString} instead
+ * Parses a float from a string, stripping non-numeric characters
+ * @param str - The string to parse
+ * @returns The parsed number, or undefined if the string is invalid
  */
 export declare function parseFloatFromString(str: string): number | undefined;
 /**
- * Arrotonda un valore a 0.5
- * @param {number | null | undefined} value - Il valore da arrotondare
- * @returns {number | null} Il valore arrotondato a 0.5 o null se l'input non è un numero valido
+ * Rounds a value to the nearest 0.5
+ * @param value - The value to round
+ * @returns The rounded value, or null if the input is not a valid number
  */
 export declare function roundToDot5(value: number | null | undefined): number | null;
 /**
- * Converte vari formati di input in un array di coordinate {lat, lng}
- * Formati supportati:
- * 1. POLYGON MySQL: "POLYGON((lon1 lat1, lon2 lat2))"
- * 2. JSON Array con oggetti {LAT,LNG} (case insensitive)
- * 3. URL encoded JSON Array
+ * Converts various input formats into an array of {lat, lng} coordinates.
+ * Supported formats:
+ * 1. MySQL POLYGON: "POLYGON((lon1 lat1, lon2 lat2))"
+ * 2. JSON array of {LAT, LNG} objects (case insensitive)
+ * 3. URL-encoded JSON array
  *
- * @param {string} input - Stringa nel formato POLYGON, JSON o URL encoded
- * @returns {Array<{lat: number, lng: number}>} Array di coordinate nel formato [{lat, lng}]
+ * @param input - String in POLYGON, JSON, or URL-encoded format
+ * @returns Array of coordinates as [{lat, lng}]
  */
 export declare function convertPolygonStringToArray(input: string): Array<{
     lat: number;
     lng: number;
 }>;
 /**
- * Converte vari formati di input in un valore booleano
- * Formati supportati:
- * 1. Stringhe: "true", "false", "1", "0", "yes", "no", "on", "off"
- * 2. Booleani: true, false
- * 3. Numeri: 1, 0
- * 4. Null, undefined
+ * Converts various input formats into a boolean value.
+ * Supported formats:
+ * 1. Strings: "true", "false", "1", "0", "yes", "no", "on", "off"
+ * 2. Booleans: true, false
+ * 3. Numbers: 1, 0
+ * 4. null, undefined
  *
- * @param {string | boolean | number | null | undefined} value - Valore da convertire
- * @returns {boolean} Valore booleano corrispondente
+ * @param value - The value to convert
+ * @returns The corresponding boolean value
  */
 export declare function parseBoolean(value: string | boolean | number | null | undefined): boolean;