docs(typedoc): document function examples

docs/modules.md

@@ -36,9 +36,16 @@ Capitalizes first character of the given string
 
 new string
 
+**`Example`**
+
+```ts
+// Prints "Lorem ipsum"
+console.log(capitalizeFirstChar("lorem ipsum"))
+```
+
 #### Defined in
 
-[functions/capitalizeFirstChar.ts:26](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/capitalizeFirstChar.ts#L26)
+[functions/capitalizeFirstChar.ts:32](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/capitalizeFirstChar.ts#L32)
 
 ___
 
@@ -60,9 +67,18 @@ Conditionally joins given class strings
 
 new string
 
+**`Example`**
+
+```ts
+let isVisible = false
+
+// prints "bg-blue-300 hidden"
+console.log(classNames("bg-blue-300", isVisible ? "block" : "hidden"))
+```
+
 #### Defined in
 
-[functions/classNames.ts:26](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/classNames.ts#L26)
+[functions/classNames.ts:34](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/classNames.ts#L34)
 
 ___
 
@@ -85,9 +101,18 @@ Conditionally joins given strings
 
 new string
 
+**`Example`**
+
+```ts
+let isAdmin = true
+
+// prints "Hello, Administrator!"
+console.log(conditionalJoin(["Hello,", isAdmin ? "Administrator" : "User", "!"], " "))
+```
+
 #### Defined in
 
-[functions/conditionalJoin.ts:27](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/conditionalJoin.ts#L27)
+[functions/conditionalJoin.ts:35](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/conditionalJoin.ts#L35)
 
 ___
 
@@ -101,8 +126,8 @@ Weakly compares two objects
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `obj1` | `object` | first object to compare with second |
+| `obj1` | `object` | first object for comparison |
-| `obj2` | `object` | second object to compare with first |
+| `obj2` | `object` | second object for comparison |
 
 #### Returns
 
@@ -114,9 +139,28 @@ true if equal
 
 uses JSON.stringify()
 
+**`Example`**
+
+```ts
+// prints false
+console.log(isDeepWeakEqual({ a: 1 }, ["lorem"]))
+
+// prints true
+console.log(isDeepWeakEqual({ a: 1 }, { a: 1 }))
+
+// prints true
+// snippet displaying the weak equality of this function
+console.log(
+  isDeepWeakEqual(
+    { date: "2024-03-12T18:19:50.548Z" },
+    { date: new Date(1710267590548) },
+  ),
+);
+```
+
 #### Defined in
 
-[functions/isDeepWeakEqual.ts:29](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/isDeepWeakEqual.ts#L29)
+[functions/isDeepWeakEqual.ts:47](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/isDeepWeakEqual.ts#L47)
 
 ___
 
@@ -144,9 +188,16 @@ number [min; max]
 Uses Math.random(), which is not cryptographically secure
 Returns only integers
 
+**`Example`**
+
+```ts
+// prints 66
+console.log(randomInRange(1, 100))
+```
+
 #### Defined in
 
-[functions/randomInRange.ts:31](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/randomInRange.ts#L31)
+[functions/randomInRange.ts:37](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/randomInRange.ts#L37)
 
 ___
 
@@ -180,9 +231,19 @@ modified array
 This method doesn't support deep comparements.
 Vulnerable to generic object injection sink
 
+**`Example`**
+
+```ts
+// prints [{ a: "1", b: "0" }, { a: "2", b: "0" }]
+console.log(removeFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { a: "3" }))
+
+// prints []
+console.log(removeFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { b: "0" }))
+```
+
 #### Defined in
 
-[functions/removeFromArrayByKeyValue.ts:31](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/removeFromArrayByKeyValue.ts#L31)
+[functions/removeFromArrayByKeyValue.ts:40](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/removeFromArrayByKeyValue.ts#L40)
 
 ___
 
@@ -212,9 +273,16 @@ Removes an object property by provided key
 
 new object
 
+**`Example`**
+
+```ts
+// print { a: "1", b: "2" }
+console.log(removeObjectProperty({ a: "1", b: "2", c: "3" }, "c"))
+```
+
 #### Defined in
 
-[functions/removeObjectProperty.ts:27](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/removeObjectProperty.ts#L27)
+[functions/removeObjectProperty.ts:33](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/removeObjectProperty.ts#L33)
 
 ___
 
@@ -249,9 +317,20 @@ modified array
 This method doesn't support deep comparements.
 Vulnerable to generic object injection sink
 
+**`Example`**
+
+```ts
+// prints [{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "lorem" }]
+console.log(replaceFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { a: "3" }, { b: "lorem" }))
+
+// prints [{ a: "lorem", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }]
+// replaces only the first occurance
+console.log(replaceFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { b: "0" }, { a: "lorem" }))
+```
+
 #### Defined in
 
-[functions/replaceFromArrayByKeyValue.ts:32](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/replaceFromArrayByKeyValue.ts#L32)
+[functions/replaceFromArrayByKeyValue.ts:42](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/replaceFromArrayByKeyValue.ts#L42)
 
 ___
 
@@ -280,6 +359,13 @@ Splits an array into chunks
 
 array of chunks
 
+**`Example`**
+
+```ts
+// prints [["a", "b", "c"], ["d", "e", "f"]]
+console.log(splitIntoChunks(["a", "b", "c", "d", "e", "f"], 3));
+```
+
 #### Defined in
 
-[functions/splitIntoChuks.ts:27](https://git.resultium.net/public/utils/src/commit/ed72704/src/functions/splitIntoChuks.ts#L27)
+[functions/splitIntoChuks.ts:33](https://git.resultium.net/public/utils/src/commit/ec41aeb/src/functions/splitIntoChuks.ts#L33)

src/functions/capitalizeFirstChar.ts

@@ -20,6 +20,12 @@
 /**
  * Capitalizes first character of the given string
  *
+ * @example
+ * ```ts
+ * // Prints "Lorem ipsum"
+ * console.log(capitalizeFirstChar("lorem ipsum"))
+ * ```
+ *
  * @param string - string to modify
  * @returns new string
  */

src/functions/classNames.ts

@@ -20,6 +20,14 @@
 /**
  * Conditionally joins given class strings
  *
+ * @example
+ * ```ts
+ * let isVisible = false
+ *
+ * // prints "bg-blue-300 hidden"
+ * console.log(classNames("bg-blue-300", isVisible ? "block" : "hidden"))
+ * ```
+ *
  * @param classes - class strings to join
  * @returns new string
  */

src/functions/conditionalJoin.ts

@@ -20,6 +20,14 @@
 /**
  * Conditionally joins given strings
  *
+ * @example
+ * ```ts
+ * let isAdmin = true
+ *
+ * // prints "Hello, Administrator!"
+ * console.log(conditionalJoin(["Hello,", isAdmin ? "Administrator" : "User", "!"], " "))
+ * ```
+ *
  * @param array - strings to join
  * @param joinChar - character used to join strings
  * @returns new string

src/functions/isDeepWeakEqual.ts

@@ -22,8 +22,26 @@
  *
  * @remarks uses JSON.stringify()
  *
- * @param obj1 - first object to compare with second
+ * @example
- * @param obj2 - second object to compare with first
+ * ```ts
+ * // prints false
+ * console.log(isDeepWeakEqual({ a: 1 }, ["lorem"]))
+ *
+ * // prints true
+ * console.log(isDeepWeakEqual({ a: 1 }, { a: 1 }))
+ *
+ * // prints true
+ * // snippet displaying the weak equality of this function
+ * console.log(
+ *   isDeepWeakEqual(
+ *     { date: "2024-03-12T18:19:50.548Z" },
+ *     { date: new Date(1710267590548) },
+ *   ),
+ * );
+ * ```
+ *
+ * @param obj1 - first object for comparison
+ * @param obj2 - second object for comparison
  * @returns true if equal
  */
 export const isDeepWeakEqual = (obj1: object, obj2: object) =>

src/functions/randomInRange.ts

@@ -24,6 +24,12 @@
  * Uses Math.random(), which is not cryptographically secure
  * Returns only integers
  *
+ * @example
+ * ```ts
+ * // prints 66
+ * console.log(randomInRange(1, 100))
+ * ```
+ *
  * @param min - minimum acceptable value
  * @param max - maximum acceptable value
  * @returns number [min; max]

src/functions/removeFromArrayByKeyValue.ts

@@ -24,6 +24,15 @@
  * This method doesn't support deep comparements.
  * Vulnerable to generic object injection sink
  *
+ * @example
+ * ```ts
+ * // prints [{ a: "1", b: "0" }, { a: "2", b: "0" }]
+ * console.log(removeFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { a: "3" }))
+ *
+ * // prints []
+ * console.log(removeFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { b: "0" }))
+ * ```
+ *
  * @param array - array which shall be manipulated with
  * @param keyValue - key-value object which defines which object shall be removed from the array
  * @returns modified array

src/functions/removeObjectProperty.ts

@@ -20,6 +20,12 @@
 /**
  * Removes an object property by provided key
  *
+ * @example
+ * ```ts
+ * // print { a: "1", b: "2" }
+ * console.log(removeObjectProperty({ a: "1", b: "2", c: "3" }, "c"))
+ * ```
+ *
  * @param object - object which shall be manipulated
  * @param key - key which should be used to remove a property from object
  * @returns new object

src/functions/replaceFromArrayByKeyValue.ts

@@ -24,6 +24,16 @@
  * This method doesn't support deep comparements.
  * Vulnerable to generic object injection sink
  *
+ * @example
+ * ```ts
+ * // prints [{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "lorem" }]
+ * console.log(replaceFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { a: "3" }, { b: "lorem" }))
+ *
+ * // prints [{ a: "lorem", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }]
+ * // replaces only the first occurance
+ * console.log(replaceFromArrayByKeyValue([{ a: "1", b: "0" }, { a: "2", b: "0" }, { a: "3", b: "0" }], { b: "0" }, { a: "lorem" }))
+ * ```
+ *
  * @param array - array which shall be manipulated with
  * @param keyValue - key-value object which defines which object shall be removed from the array
  * @param newObject - object or values to replace within the searched object
@@ -36,10 +46,9 @@ export const replaceFromArrayByKeyValue = <T>(
 ) => {
   const keys = Object.keys(keyValue) as Array<keyof T>;
 
-  const itemIndex = array.findIndex(
+  const itemIndex = array.findIndex((item) =>
-    (item) =>
+    // eslint-disable-next-line security/detect-object-injection -- warned at remarks
-      // eslint-disable-next-line security/detect-object-injection -- warned at remarks
+    keys.every((key) => item[key] === keyValue[key]),
-      !keys.every((key) => item[key] === keyValue[key]),
   );
 
   array[`${itemIndex}`] = { ...array[`${itemIndex}`], ...newObject };

src/functions/splitIntoChuks.ts

@@ -20,6 +20,12 @@
 /**
  * Splits an array into chunks
  *
+ * @example
+ * ```ts
+ * // prints [["a", "b", "c"], ["d", "e", "f"]]
+ * console.log(splitIntoChunks(["a", "b", "c", "d", "e", "f"], 3));
+ * ```
+ *
  * @param array - array which shall be split into chunks
  * @param chunkSize - size of a single chunk
  * @returns array of chunks