docs(typedoc): document function examples

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
- * @param obj2 - second object to compare with first
+ * @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) },
+ *   ),
+ * );
+ * ```
+ *
+ * @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(
-    (item) =>
-      // eslint-disable-next-line security/detect-object-injection -- warned at remarks
-      !keys.every((key) => item[key] === keyValue[key]),
+  const itemIndex = array.findIndex((item) =>
+    // eslint-disable-next-line security/detect-object-injection -- warned at remarks
+    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