@webalternatif/js-core 1.6.0 → 1.6.3

package/docs/math.md

@@ -0,0 +1,47 @@
+# Math Utilities
+
+Description of the math utilities.
+
+## Import
+
+```js
+import { math } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:math -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## dec2hex
+
+[src/math.js:79-82][1]
+
+Converts a decimal number into hexadecimal
+
+### Parameters
+
+*   `n` **[number][2]**&#x20;
+
+Returns **[string][3]**&#x20;
+
+## hex2dec
+
+[src/math.js:90-109][4]
+
+Converts a hexadecimal into a decimal number
+
+### Parameters
+
+*   `hex` **[string][3]**&#x20;
+
+Returns **[number][2]**&#x20;
+
+[1]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/math.js#L79-L82 "Source code on GitHub"
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[4]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/math.js#L90-L109 "Source code on GitHub"

package/docs/mouse.md

@@ -0,0 +1,15 @@
+# Mouse Utilities
+
+Description of the mouse utilities.
+
+## Import
+
+```js
+import { mouse } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:mouse -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

package/docs/random.md

@@ -0,0 +1,15 @@
+# Random Utilities
+
+Description of the random utilities.
+
+## Import
+
+```js
+import { random } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:random -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

package/docs/string.md

@@ -0,0 +1,145 @@
+# String Utilities
+
+Description of the string utilities.
+
+## Import
+
+```js
+import { string } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:string -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## pad
+
+Pads a string to a specified length with a specified string and padding type
+
+### Parameters
+
+*   `str` **[string][1]**&#x20;
+*   `pad_length` **[number][2]**&#x20;
+*   `pad_str` **[string][1]?**  (optional, default `' '`)
+*   `pad_type` **[string][1]?**  (optional, default `'left'`)
+
+Returns **[string][1]**&#x20;
+
+## rgb2hex
+
+Converts RGB values to a hexadecimal color string.
+
+### Parameters
+
+*   `r` **([number][2] | [Array][3]<[number][2]>)** Either an array representing a RGB color (e.g. \[255, 0, 0]) or the red component as a
+    number (0-255).
+*   `g` **[number][2]?** The green component (0-255). Required if `r` is a number.
+*   `b` **[number][2]?** The blue component (0-255). Required if `r` is a number.
+
+### Examples
+
+```javascript
+// Using separate RGB components
+rgb2hex(255, 0, 0); // Returns 'FF0000'
+```
+
+```javascript
+// Using an array of RGB components
+rgb2hex([255, 0, 0]); // Returns 'FF0000'
+```
+
+Returns **[string][1]** The hexadecimal color string (e.g., 'FF0000').
+
+## hex2rgb
+
+Converts a hexadecimal color to RGB values.
+
+### Parameters
+
+*   `hex` **[string][1]** The hexadecimal value (e.g #FF0000)
+
+Returns **[Array][3]<[number][2]>** The RGB color array (e.g \[255, 0, 0]).
+
+## parse\_url
+
+Parses a URL string into its components.
+
+### Parameters
+
+*   `str` **[string][1]** The URL string to be parsed.
+
+### Properties
+
+*   `scheme` **[string][1]?** The scheme (protocol) of the URL (e.g., `http`, `https`).
+*   `authority` **[string][1]?** The authority part of the URL.
+*   `userInfo` **[string][1]?** The user information (e.g., `user:pass`).
+*   `user` **[string][1]?** The username from the user information.
+*   `pass` **[string][1]?** The password from the user information.
+*   `host` **[string][1]?** The host of the URL (e.g., `example.com`).
+*   `port` **[string][1]?** The port of the URL (e.g., `8080`).
+*   `relative` **[string][1]?** The relative URL.
+*   `path` **[string][1]?** The path of the URL (e.g., `/path/to/resource`).
+*   `directory` **[string][1]?** The directory of the URL path.
+*   `file` **[string][1]?** The file name from the path, if applicable.
+*   `query` **[string][1]?** The query string (e.g., `key=value&key2=value2`).
+*   `fragment` **[string][1]?** The fragment (hash) of the URL (e.g., `#section`).
+
+Returns **[Object][4]** An object containing the parsed components of the URL.
+
+## addUrlParam
+
+Adds or updates one or more query parameters to a given URL.
+
+### Parameters
+
+*   `url` **[string][1]** The URL to which the parameters should be added.
+*   `param` **([string][1] | [Object][4])** The key of the parameter to add, or an object containing multiple key-value pairs to add.
+*   `value` **([string][1] | null)** The value of the parameter to add. Ignored if `param` is an object. (optional, default `null`)
+
+### Examples
+
+Add a single parameter to a URL without a query string
+
+```javascript
+addUrlParam('https://example.com', 'key', 'value');
+// Returns: 'https://example.com?key=value'
+```
+
+Add multiple parameters to a URL
+
+```javascript
+addUrlParam('https://example.com', { key1: 'value1', key2: 'value2' });
+// Returns: 'https://example.com?key1=value1&key2=value2'
+```
+
+Returns **[string][1]** The updated URL with the new query parameters.
+
+## escapeRegex
+
+*   **See**: [http://stackoverflow.com/questions/3115150/how-to-escape-regular-expression-special-characters-using-javascript][5]
+
+### Parameters
+
+*   `str` &#x20;
+
+## toCssClassName
+
+*   **See**: [https://stackoverflow.com/questions/7627000/javascript-convert-string-to-safe-class-name-for-css][6]
+
+### Parameters
+
+*   `str` &#x20;
+
+[1]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[5]: http://stackoverflow.com/questions/3115150/how-to-escape-regular-expression-special-characters-using-javascript
+
+[6]: https://stackoverflow.com/questions/7627000/javascript-convert-string-to-safe-class-name-for-css

package/docs/translator.md

@@ -0,0 +1,95 @@
+# Translator
+
+Description of the translator.
+
+## Import
+
+```js
+import { translator } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:translator -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Translator
+
+[src/Translator.js:20-142][1]
+
+### Parameters
+
+*   `mapping` &#x20;
+*   `defaultLang` &#x20;
+
+### translate
+
+[src/Translator.js:61-75][2]
+
+#### Parameters
+
+*   `label` **[string][3]**&#x20;
+*   `lang` **[string][3]?**&#x20;
+*   `namespace` **[string][3]**  (optional, default `'core'`)
+
+Returns **[string][3]**&#x20;
+
+### translateFrom
+
+[src/Translator.js:83-100][4]
+
+#### Parameters
+
+*   `label` **[string][3]**&#x20;
+*   `from` **[string][3]** Language from.
+*   `to` **[string][3]** Language to.
+*   `namespace` **[string][3]**  (optional, default `'core'`)
+
+## TranslatorNsMapping
+
+[src/Translator.js:20-142][5]
+
+Type: Record<[string][3], Record<[string][3], Record<[string][3], TranslatorValue>>>
+
+## TranslatorCoreMapping
+
+[src/Translator.js:20-142][6]
+
+Type: Record<[string][3], Record<[string][3], TranslatorValue>>
+
+## TranslatorMapping
+
+[src/Translator.js:20-142][7]
+
+Type: ([TranslatorNsMapping][8] | [TranslatorCoreMapping][9])
+
+## lang
+
+[src/Translator.js:22-22][10]
+
+## mapping
+
+[src/Translator.js:25-25][11]
+
+[1]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L20-L142 "Source code on GitHub"
+
+[2]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L61-L75 "Source code on GitHub"
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[4]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L83-L100 "Source code on GitHub"
+
+[5]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L8-L10 "Source code on GitHub"
+
+[6]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L12-L14 "Source code on GitHub"
+
+[7]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L16-L18 "Source code on GitHub"
+
+[8]: #translatornsmapping
+
+[9]: #translatorcoremapping
+
+[10]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L22-L22 "Source code on GitHub"
+
+[11]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/Translator.js#L25-L25 "Source code on GitHub"

package/docs/traversal.md

@@ -0,0 +1,159 @@
+# Traversal Utilities
+
+Description of the traversal utilities.
+
+## Import
+
+```js
+import { traversal } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:traversal -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## Collection
+
+[src/traversal.js:24-70][1]
+
+Type: ([Array][2]\<T> | [Set][3]\<T> | [Map][4]\<any, T> | [Object][5]<[string][6], T> | [string][6] | [Array][2]<[string][6]>)
+
+## each
+
+[src/traversal.js:24-70][7]
+
+Iterates over Arrays, Strings, Maps, Sets and plain Objects.
+
+The callback receives:
+(keyOrIndex, value, o, index)
+
+If the callback returns `false`, the iteration stops.
+
+### Parameters
+
+*   `o` **[Collection][8]\<T>**&#x20;
+*   `callback` &#x20;
+*   `context` **any?** Optional "this" binding for the callback
+
+## foreach
+
+[src/traversal.js:84-86][9]
+
+Same as each except that key and value are reversed in callback
+
+The callback receives:
+(value, keyOrIndex, o, index)
+
+### Parameters
+
+*   `o` **[Collection][8]\<T>**&#x20;
+*   `callback` &#x20;
+*   `context` **any?** Optional "this" binding for the callback
+
+## map
+
+[src/traversal.js:103-114][10]
+
+Iterates over Arrays, Strings, Maps, Sets and plain Objects.
+Returns an array from the callback results.
+Values strictly equal to `null` are skipped.
+Values strictly equal to `false` stops the iteration.
+
+The callback receives:
+(keyOrIndex, value, o, index)
+
+### Parameters
+
+*   `o` **[Collection][8]\<T>**&#x20;
+*   `callback` &#x20;
+*   `context` **any?** Optional "this" binding for the callback
+
+Returns **[Array][2]\<R>** Returns the resulted array
+
+## reduce
+
+[src/traversal.js:128-144][11]
+
+Reduces a collection to a single value
+
+The reducer receives:
+(accumulator, value, index, source)
+
+### Parameters
+
+*   `o` **[Collection][8]\<T>**&#x20;
+*   `callback` &#x20;
+*   `initialValue` **R?** la valeur initiale
+
+Returns **R** Returns the accumulated value
+
+## extend
+
+[src/traversal.js:154-183][12]
+
+Creates a shallow or deep copy of one or more objects or arrays
+If the first argument is `true`, nested plain objects are merged recursively.
+
+### Parameters
+
+*   `args` **...([boolean][13] | T)**&#x20;
+
+Returns **T** A copy of the merged result
+
+## clone
+
+[src/traversal.js:192-208][14]
+
+Creates a deep copy of an Object or Array
+
+### Parameters
+
+*   `o` **T**&#x20;
+
+Returns **T** The copy of o
+
+## merge
+
+[src/traversal.js:219-232][15]
+
+Merge multiple collections into a single array
+
+### Parameters
+
+*   `first` **[Collection][8]\<T>**&#x20;
+*   `second` **[Collection][8]\<T>?**  (optional, default `[]`)
+*   `args` **...[Collection][8]\<T>** Remaining collections to merge
+
+Returns **[Array][2]\<T>** the resulted merged array
+
+[1]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L5-L8 "Source code on GitHub"
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Set
+
+[4]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Map
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String
+
+[7]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L24-L70 "Source code on GitHub"
+
+[8]: #collection
+
+[9]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L84-L86 "Source code on GitHub"
+
+[10]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L103-L114 "Source code on GitHub"
+
+[11]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L128-L144 "Source code on GitHub"
+
+[12]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L154-L183 "Source code on GitHub"
+
+[13]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean
+
+[14]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L192-L208 "Source code on GitHub"
+
+[15]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/traversal.js#L219-L232 "Source code on GitHub"

package/docs/utils.md

@@ -0,0 +1,75 @@
+# General Utilities
+
+Description of the general utilities.
+
+## Import
+
+```js
+import { utils } from '@webalternatif/js-core'
+```
+
+---
+
+## API
+<!-- GENERATED:utils -->
+<!-- Generated by documentation.js. Update this documentation by updating the source code. -->
+
+## flatten
+
+[src/utils.js:53-59][1]
+
+Recursively flattens an object or array into a single-level array.
+
+### Parameters
+
+*   `o` **([Object][2] | [Array][3])** The object or array to flatten.
+
+### Examples
+
+Flatten an array of arrays
+
+```javascript
+const result = flatten([1, [2, [3, 4]], 5]);
+console.log(result);
+// Output: [1, 2, 3, 4, 5]
+```
+
+Flatten an object
+
+```javascript
+const result = flatten({ a: 1, b: [2, { c: 3 }], d: 4 });
+console.log(result);
+// Output: [1, 2, 3, 4]
+```
+
+Returns **[Array][3]** A flattened array containing all the values from the input object or array.
+
+## debounce
+
+[src/utils.js:105-129][4]
+
+Creates a debounced function that delays the invocation of `func` until after `wait` milliseconds
+have elapsed since the last time the debounced function was invoked.
+
+### Parameters
+
+*   `func` **[Function][5]** The function to debounce.
+*   `wait` **[number][6]** The number of milliseconds to delay.
+*   `immediate` **[boolean][7]** If true, execute `func` on the leading edge instead of the trailing. (optional, default `false`)
+*   `context` **[Object][2]** The context to bind to `func`. (optional, default `null`)
+
+Returns **[Function][5]** The debounced function.
+
+[1]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/utils.js#L53-L59 "Source code on GitHub"
+
+[2]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object
+
+[3]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array
+
+[4]: https://github.com/webalternatif/js-core/blob/c9158e27ed191c37c696ced37950f978a21eecba/src/utils.js#L105-L129 "Source code on GitHub"
+
+[5]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function
+
+[6]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number
+
+[7]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

package/package.json

@@ -1,6 +1,18 @@
 {
   "name": "@webalternatif/js-core",
-  "version": "1.6.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/webalternatif/js-core.git"
+  },
+  "bugs": {
+    "url": "https://github.com/webalternatif/js-core/issues"
+  },
+  "homepage": "https://github.com/webalternatif/js-core#readme",
+  "author": {
+    "name": "Ludovic Tarit",
+    "email": "ludovic.tarit@webalternatif.com"
+  },
+  "version": "1.6.3",
   "type": "module",
   "types": "types/index.d.ts",
   "main": "dist/cjs/index.js",
@@ -33,6 +45,7 @@
     "@babel/core": "^7.26.0",
     "@babel/plugin-transform-export-namespace-from": "^7.27.1",
     "@babel/preset-env": "^7.26.0",
+    "@eslint/js": "^9.39.2",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@types/jest": "^29.5.14",
@@ -40,16 +53,29 @@
     "babel-loader": "^9.2.1",
     "cross-env": "^10.1.0",
     "documentation": "^14.0.3",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.5",
+    "globals": "^17.2.0",
+    "husky": "^9.1.7",
     "jest": "^29.7.0",
     "jest-environment-jsdom": "^29.7.0",
+    "lint-staged": "^16.2.7",
     "nodemon": "^3.1.9",
-    "typescript": "^5.7.2",
-    "husky": "^8.0.0"
+    "prettier": "^3.8.1",
+    "typescript": "^5.7.2"
   },
   "files": [
     "dist",
     "types",
     "README.md",
+    "docs",
     "LICENSE"
-  ]
+  ],
+  "lint-staged": {
+    "*.js": [
+      "eslint --fix",
+      "prettier --write"
+    ]
+  }
 }

package/types/array.d.ts

@@ -1,9 +1,9 @@
 export function inArray(value: any, arr: Object | any[], index?: number, strict?: boolean): boolean;
 export function indexOf(arr: Array<any> | string, elt: any, from?: number): number;
 export function lastIndexOf(arr: Array<any> | string, elt: any, from?: number): number;
-export function compareArray(a1: any, a2: any): any;
+export function compareArray(a1: any[], a2: any[]): boolean;
 export function arrayUnique(arr: any): any;
 export function array_unique(arr: any): any;
 export function arrayDiff(array1: any, array2: any, strict?: boolean): any;
-export function array_diff(arr: any): any;
+export function array_diff(array1: any, array2: any, strict?: boolean): any;
 export function range(size: any, startAt?: number, step?: number): any[];

package/types/dom.d.ts

@@ -7,9 +7,9 @@ declare namespace dom {
     /**
      * @param {Element} el
      * @param {string} [selector]
-     * @returns {NodeList}
+     * @returns {NodeList|Element[]}
      */
-    export function children(el: Element, selector?: string): NodeList;
+    export function children(el: Element, selector?: string): NodeList | Element[];
     /**
      * @param {Element} el
      * @param {string} [selector]
@@ -25,9 +25,9 @@ declare namespace dom {
     /**
      * @param {Element|Document|string} refEl
      * @param {string|Element|NodeList|Array<Element>} [selector]
-     * @returns {Array<Element>}
+     * @returns {Element[]}
      */
-    export function find(refEl: Element | Document | string, selector?: string | Element | NodeList | Array<Element>): Array<Element>;
+    export function find(refEl: Element | Document | string, selector?: string | Element | NodeList | Array<Element>): Element[];
     /**
      * @param {Element|string} el
      * @param {string} data

package/types/index.d.ts

@@ -60,11 +60,11 @@ declare const webf: {
     inArray: (value: any, arr: Object | any[], index?: number, strict?: boolean) => boolean;
     indexOf: (arr: Array<any> | string, elt: any, from?: number) => number;
     lastIndexOf: (arr: Array<any> | string, elt: any, from?: number) => number;
-    compareArray: (a1: any, a2: any) => any;
+    compareArray: (a1: any[], a2: any[]) => boolean;
     arrayUnique: (arr: any) => any;
     array_unique: (arr: any) => any;
     arrayDiff: (array1: any, array2: any, strict?: boolean) => any;
-    array_diff: (arr: any) => any;
+    array_diff: (array1: any, array2: any, strict?: boolean) => any;
     range: (size: any, startAt?: number, step?: number) => any[];
     trim: (str: any, char?: string) => any;
     ltrim: (str: any, char?: string) => any;