From fdb28fa6127a513c4dd280802be94f80aca378e4 Mon Sep 17 00:00:00 2001 From: Olivers Vitins Date: Tue, 12 Mar 2024 20:42:34 +0200 Subject: [PATCH] docs(typedoc): document function examples --- docs/modules.md | 108 ++++++++++++++++++-- src/functions/capitalizeFirstChar.ts | 6 ++ src/functions/classNames.ts | 8 ++ src/functions/conditionalJoin.ts | 8 ++ src/functions/isDeepWeakEqual.ts | 22 +++- src/functions/randomInRange.ts | 6 ++ src/functions/removeFromArrayByKeyValue.ts | 9 ++ src/functions/removeObjectProperty.ts | 6 ++ src/functions/replaceFromArrayByKeyValue.ts | 17 ++- src/functions/splitIntoChuks.ts | 6 ++ 10 files changed, 179 insertions(+), 17 deletions(-) diff --git a/docs/modules.md b/docs/modules.md index d177f47..1e76d60 100644 --- a/docs/modules.md +++ b/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 | -| `obj2` | `object` | second object to compare with first | +| `obj1` | `object` | first object for comparison | +| `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) diff --git a/src/functions/capitalizeFirstChar.ts b/src/functions/capitalizeFirstChar.ts index 0949981..5e99f7b 100644 --- a/src/functions/capitalizeFirstChar.ts +++ b/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 */ diff --git a/src/functions/classNames.ts b/src/functions/classNames.ts index 0d4bb93..1a4a25b 100644 --- a/src/functions/classNames.ts +++ b/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 */ diff --git a/src/functions/conditionalJoin.ts b/src/functions/conditionalJoin.ts index 77bdbc3..e02de83 100644 --- a/src/functions/conditionalJoin.ts +++ b/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 diff --git a/src/functions/isDeepWeakEqual.ts b/src/functions/isDeepWeakEqual.ts index d5f640a..0180f58 100644 --- a/src/functions/isDeepWeakEqual.ts +++ b/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) => diff --git a/src/functions/randomInRange.ts b/src/functions/randomInRange.ts index e3f9d8e..983097d 100644 --- a/src/functions/randomInRange.ts +++ b/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] diff --git a/src/functions/removeFromArrayByKeyValue.ts b/src/functions/removeFromArrayByKeyValue.ts index 72b7234..7c8ae77 100644 --- a/src/functions/removeFromArrayByKeyValue.ts +++ b/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 diff --git a/src/functions/removeObjectProperty.ts b/src/functions/removeObjectProperty.ts index faad2b0..b1c796d 100644 --- a/src/functions/removeObjectProperty.ts +++ b/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 diff --git a/src/functions/replaceFromArrayByKeyValue.ts b/src/functions/replaceFromArrayByKeyValue.ts index f9d5957..568187e 100644 --- a/src/functions/replaceFromArrayByKeyValue.ts +++ b/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 = ( ) => { const keys = Object.keys(keyValue) as Array; - 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 }; diff --git a/src/functions/splitIntoChuks.ts b/src/functions/splitIntoChuks.ts index 15dcaff..992cad5 100644 --- a/src/functions/splitIntoChuks.ts +++ b/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