topkat-utils 1.2.117 → 1.3.4

package/package.json

@@ -1,21 +1,58 @@
 {
   "name": "topkat-utils",
-  "version": "1.2.117",
+  "version": "1.3.4",
   "type": "commonjs",
   "types": "index.ts",
   "main": "dist",
-  "description": "FAST AND FUNCTIONAL UTILS",
-  "author": "topkat",
-  "license": "ISC",
+  "description": "A comprehensive collection of TypeScript/JavaScript utility functions for common programming tasks. Includes validation, object manipulation, date handling, string formatting, and more. Zero dependencies, fully typed, and optimized for performance.",
+  "keywords": [
+    "typescript",
+    "javascript",
+    "utils",
+    "utilities",
+    "validation",
+    "date",
+    "string",
+    "object",
+    "array",
+    "url",
+    "path",
+    "logger",
+    "error-handling",
+    "functional",
+    "zero-dependencies",
+    "performance",
+    "type-safe",
+    "dot-notation",
+    "template-engine",
+    "deep-clone",
+    "merge",
+    "flatten",
+    "case-conversion"
+  ],
+  "author": "https://github.com/top-kat",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/top-kat/utils.git"
   },
+  "bugs": {
+    "url": "https://github.com/top-kat/utils/issues"
+  },
+  "homepage": "https://github.com/top-kat/utils#readme",
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
-    "bump:major": "yarn test:ci && npm run build && node node_modules/bump-simple/bump-simple.js --major",
-    "bump:minor": "yarn test:ci && npm run build && node node_modules/bump-simple/bump-simple.js --minor",
-    "bump:patch": "yarn test:ci && npm run build && node node_modules/bump-simple/bump-simple.js --patch",
+    "// Please run BUMP command with NPM not Yarn": "",
+    "bump": "yarn test:ci && yarn build && bump --patch",
+    "bump:major": "yarn test:ci && yarn build && bump --major",
+    "bump:minor": "yarn test:ci && yarn build && bump --minor",
+    "bump:patch": "yarn test:ci && yarn build && bump --patch",
     "test": "jest --watchAll",
     "test:ci": "jest --ci --runInBand --maxConcurrency=1 --silent"
   },
@@ -24,8 +61,8 @@
     "@types/node": "^18.11.18",
     "@typescript-eslint/eslint-plugin": "latest",
     "@typescript-eslint/parser": "latest",
-    "bump-simple": "^1.0.0",
     "eslint": "^8.0.0",
+    "bump-simple": "^1.0.29",
     "jest": "^29.7.0",
     "ts-jest": "^29.2.4",
     "ts-node": "^10.9.2",

package/src/clean-stack-trace.ts

@@ -25,6 +25,7 @@ export function cleanStackTrace(stack) {
         'Object.throw',
         'mongoose/lib/utils',
         'at Array.forEach (<anonymous>)',
+        '/core.error.'
     ]
     const linesClean = lines
         .map((line, i) => {

package/src/error-utils.ts

@@ -51,7 +51,7 @@ export const failSafe = tryCatch // ALIAS
 function extraInfosRendererDefault(extraInfos) {
     return [
         '== EXTRA INFOS ==',
-        removeCircularJSONstringify(extraInfos, 2)
+        removeCircularJSONstringify({ ...extraInfos, msg: undefined, message: undefined }, 2)
     ]
 }
 

package/src/loop-utils.ts

@@ -5,7 +5,37 @@ import { ObjectGeneric } from './types'
 import { err500IfNotSet } from './error-utils'
 import { isObject } from './is-object'
 
-export function forI<T extends any[] | any>(nbIterations: number, callback: (number: number, previousValue, arrayOfPreviousValues: any[]) => T): T[] {
+/**
+ * Iterates over a specified number of times, passing each iteration's result to the next callback
+ * @returns Array containing results from all iterations
+ *
+ * @example
+ * ```typescript
+ * // Generate Fibonacci sequence
+ * forI(8, (i, prev, results) => {
+ *   if (i <= 1) return 1
+ *   return results[i-1] + results[i-2]
+ * })
+ * ```
+ * // Returns: [1, 1, 2, 3, 5, 8, 13, 21]
+ */
+export function forI<T extends any[] | any>(
+    /** Number of times to iterate */
+    nbIterations: number,
+    /** Function called for each iteration with:
+     *   - number: Current iteration index (0-based)
+     *   - previousValue: Result from previous iteration
+     *   - arrayOfPreviousValues: Array of all previous results
+     */
+    callback: (
+        /** Current iteration index (0-based) */
+        number: number,
+        /** Result from previous iteration */
+        previousValue,
+        /** Array of all previous results */
+        arrayOfPreviousValues: any[]
+    ) => T
+): T[] {
     const results: any[] = []
     for (let i = 0; i < nbIterations; i++) {
         const prevValue = results[results.length - 1]
@@ -14,6 +44,20 @@ export function forI<T extends any[] | any>(nbIterations: number, callback: (num
     return results
 }
 
+/**
+ * Iterates over a specified number of times, passing each iteration's result to the next callback
+ * @returns Array containing results from all iterations
+ *
+ * @example
+ * ```typescript
+ * // Generate Fibonacci sequence ASYNC
+ * await forI(8, async (i, prev, results) => {
+ *   if (i <= 1) return 1
+ *   return new Promise(resolve => setTimeout(() => resolve(results[i-1] + results[i-2]), 100))
+ * })
+ * ```
+ * // Returns: [1, 1, 2, 3, 5, 8, 13, 21]
+ */
 export async function forIasync<T extends any[] | any>(nbIterations: number, callback: (number) => T): Promise<T[]> {
     const results: any[] = []
     for (let i = 0; i < nbIterations; i++) {
@@ -43,7 +87,20 @@ export type RecursiveConfig = {
  * NOTE: will remove circular references
  * /!\ check return values
  */
-export async function recursiveGenericFunction(item: ObjectGeneric | any[], callback: RecursiveCallback, config: RecursiveConfig = {}, addr$ = '', lastElementKey: string | number = '', parent?, techFieldToAvoidCircularDependency: any[] = []) {
+export async function recursiveGenericFunction(
+    /** The object or array you want to recursively browse */
+    item: ObjectGeneric | any[],
+    /** The callback you want to apply on items including the main one */
+    callback: RecursiveCallback,
+    /** Optional configuration object */
+    config: RecursiveConfig = {},
+    /** Optional base address for the callback function */
+    addr$ = '',
+    /** Technical field */
+    lastElementKey: string | number = '',
+    parent?,
+    techFieldToAvoidCircularDependency: any[] = []
+) {
     err500IfNotSet({ callback })
 
     if (!config.isObjectTestFunction) config.isObjectTestFunction = isObject

package/src/math-utils.ts

@@ -4,9 +4,18 @@
 import { isset } from './isset'
 
 /** Round with custom number of decimals (default:0) */
-export function round(number: number | string, decimals = 0) { return Math.round((typeof number === 'number' ? number : parseFloat(number)) * Math.pow(10, decimals)) / Math.pow(10, decimals) }
+export function round(number: number | string, decimals = 0) {
+    return Math.round((typeof number === 'number' ? number : parseFloat(number)) * Math.pow(10, decimals)) / Math.pow(10, decimals)
+}
+
 /** Round with custom number of decimals (default:2) */
-export function round2(number: number | string, decimals = 2) { return round(number, decimals) }
+export function round2<T extends 'number' | 'string' = 'string'>(
+    number: number | string,
+    decimals = 2,
+    format: T = 'string' as T
+) {
+    return (format === 'string' ? Number(number).toFixed(decimals) : round(number, decimals)) as T extends 'number' ? number : string
+}
 
 /** Is number between two numbers (including those numbers) */
 export function isBetween(number: number, min: number, max: number, inclusive = true) { return inclusive ? number <= max && number >= min : number < max && number > min }

package/src/object-utils.ts

@@ -79,7 +79,7 @@ export function findByAddressAll<ReturnAddresses extends boolean = false>(
     if (addr === '') return (returnAddresses ? [addr, obj, undefined, undefined] : obj) as any
     const addrRegexp = new RegExp('^' + escapeRegexp(
         addr.replace(/\.?\[(\d+)\]/g, '.$1'), // replace .[4] AND [4] TO .4
-        { parseStarChar: true, wildcardNotMatchingChars: '.[' }) + '$'
+        { parseWildcard: true, wildcardNotMatchingChars: '.[' }) + '$'
     )
 
     const matchingItems: any[] = []
@@ -243,13 +243,16 @@ export function reassignForbidden(o) {
 }
 
 /** All fileds and subFields of the object will become readOnly */
-export function readOnlyForAll(object) {
+export function readOnlyRecursive(object) {
     recursiveGenericFunctionSync(object, (item, _, lastElementKey, parent) => {
         if (typeof item === 'object') parent[lastElementKey] = readOnly(item)
     })
     return object
 }
 
+/** @deprecated use readOnlyRecursive instead */
+export const readOnlyForAll = readOnlyRecursive
+
 export function objFilterUndefinedRecursive(obj) {
     if (obj) {
         const flattenedObj = flattenObject(obj)
@@ -396,6 +399,7 @@ export function flattenObject(data, config: { withoutArraySyntax?: boolean, with
                 for (const p in cur) recurse(cur[p], (prop ? prop + '.' : '') + p.replace(/\./g, '%')) // allow prop to contain special chars like points);
 
                 if (isEmpty && prop) result[prop] = {}
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
             } catch (error) {
                 // eslint-disable-next-line no-console
                 console.warn('Circular reference in flattenObject, impossible to parse')

package/src/regexp-utils.ts

@@ -3,13 +3,24 @@
 //----------------------------------------
 import { C } from './logger-utils'
 
-/** ESCAPE REGEXP
- * * parseStarChar => config will replace '*' by '.*?' which is the best for 'match all until'
- * * wildcardNotMatchingChars => list of characters not to match, eg: '.[' will match all except '.' and '[' /!\ will be outputted as a regexp [^.[] so don't forget to ESCAPE characters like ']' => '\]'
+/**
+ * Will escape all special character in a string to output a valid regexp string to put in RegExp(myString)
+ * * Eg: from `'path.*.addr(*)'` will output `'aa\..*?\.addr\(.*?\)'` so regexp match `'path.random.addr(randomItem)'`
+ * * Options:
+ *   * parseWildcard => config will replace '*' by '.*?' which is the best for 'match all until'
+ *   * wildcardNotMatchingChars => if provided, will replace '*' by `[^${wildcardNotMatchingChars}]` instead of '.*?'. This allows wildcard not to match certains characters
  */
-export function escapeRegexp(str: string, config: { parseStarChar?: boolean, wildcardNotMatchingChars?: string } = {}): string {
-    const { parseStarChar = false, wildcardNotMatchingChars } = config
-    if (parseStarChar) return str.replace(/[-[\]{}()+?.,\\^$|#\s]/g, '\\$&').replace(/\*/g, wildcardNotMatchingChars ? `[^${wildcardNotMatchingChars}]` : '.*?')
+export function escapeRegexp(
+    str: string,
+    config: {
+        /** will replace '*' by '.*?' which is the best for 'match all until' */
+        parseWildcard?: boolean,
+        /** if provided, will replace '*' by `[^${wildcardNotMatchingChars}]` instead of '.*?'. This allows wildcard not to match certains characters */
+        wildcardNotMatchingChars?: string
+    } = {}
+): string {
+    const { parseWildcard = false, wildcardNotMatchingChars } = config
+    if (parseWildcard) return str.replace(/[-[\]{}()+?.,\\^$|#\s]/g, '\\$&').replace(/\*/g, wildcardNotMatchingChars ? `[^${wildcardNotMatchingChars}]` : '.*?')
     else return str.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, '\\$&')
 }
 

package/src/string-utils.ts

@@ -7,12 +7,19 @@ import { isset } from './isset'
 
 const getWordBits = (wb: string[] | [string[]]): string[] => Array.isArray(wb[0]) ? wb[0] : wb as any
 
-/**Eg: camelCase */
+/**Eg: camelCase('hello', 'world') => 'helloWorld' */
 export function camelCase(...wordBits: string[] | [string[]]): string {
     const wordBitsReal = getWordBits(wordBits)
     return wordBitsReal.filter(e => e).map((w, i) => i === 0 ? w.toLowerCase() : capitalize1st(w, true)).join('')
 }
 
+/** Replace 'hello-world', 'hello World', 'hello_World', 'helloWorld' => 'helloWorld' */
+export function camelCaseify(word: string) {
+    const wordBitsReal = word.replace(/([A-Z])/g, ' $1').split(/[- _]/g)
+    return camelCase(wordBitsReal)
+}
+
+
 /**Eg: snake_case
  * trimmed but not lowerCased
  */
@@ -22,19 +29,23 @@ export function snakeCase(...wordBits: string[] | [string[]]): string {
 }
 /**Eg: kebab-case
  * trimmed AND lowerCased
- * undefined, null... => ''
+ * undefined, null are removed
  */
 export function kebabCase(...wordBits: string[] | [string[]]): string {
     const wordBitsReal = getWordBits(wordBits)
     return wordBitsReal.filter(e => e).map(w => w.trim().toLowerCase()).join('-')
 }
-/**Eg: PascalCase undefined, null... => '' */
+/**Eg: PascalCase
+ * undefined, null are removed
+ */
 export function pascalCase(...wordBits: string[] | [string[]]): string {
     const wordBitsReal = getWordBits(wordBits)
     return wordBitsReal.filter(e => e).map(w => capitalize1st(w, true)).join('')
 }
 
-/**Eg: Titlecase undefined, null... => '' */
+/**Eg: Titlecase
+ * undefined, null are removed
+ */
 export function titleCase(...wordBits: string[] | [string[]]): string {
     const wordBitsReal = getWordBits(wordBits)
     return capitalize1st(wordBitsReal.filter(e => e).map(w => w.trim()).join(''), true)
@@ -94,7 +105,7 @@ export function getValuesBetweenStrings(str: string, openingOrSeparator, closing
         // handle unwanted nested structure like characters in a strings that may be a unmatched closing / opening character
         // Eg: {'azer}aze'}
         if (ignoreUntil && char === ignoreUntil && precedingChar !== '\\') ignoreUntil = false
-        else if (ignoreUntil && char !== ignoreUntil) true
+        else if (ignoreUntil && char !== ignoreUntil) ignoreUntil = true
         else if (ignoreBetweenOpen.includes(char)) {
             const indexChar = ignoreBetweenOpen.findIndex(char2 => char2 === char)
             ignoreUntil = ignoreBetweenClose[indexChar]
@@ -203,8 +214,11 @@ export function pathJoinSafe(...pathBits: string[]) {
 
 
 export type MiniTemplaterOptions = {
+    /** replacer for undefined values */
     valueWhenNotSet: string
+    /** override default regexp that match content between `{{ }}`. It must be 'g' and first capturing group matching the value to replace. Default: /{{\s*([^}]*)\s*}}/g*/
     regexp: RegExp
+    /** replacer for undefined values */
     valueWhenContentUndefined: string
 }
 /** Replace variables in a string like: `Hello {{userName}}!`

package/src/timer-utils.ts

@@ -70,7 +70,7 @@ export async function retryWithDelay(
 }
 
 /** Use this timer to measure code performances.
-  * @example ```
+  * @example ```typescript
 const time = perfTimer()
 
 for(let i = 0; i < 9999;i++) longProcess()