public/utils
3
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(typedoc): document function examples

Browse Source
This commit is contained in:
Olivers Vītiņš
2024-03-12 20:42:34 +02:00
parent ec41aebad9
commit fdb28fa612
10 changed files with 179 additions and 17 deletions
Download Patch File Download Diff File Expand all files Collapse all files

108
docs/modules.md
View File

@@ -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)

6
src/functions/capitalizeFirstChar.ts
View File

@@ -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
*/

8
src/functions/classNames.ts
View File

@@ -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
*/

8
src/functions/conditionalJoin.ts
View File

@@ -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

22
src/functions/isDeepWeakEqual.ts
View File

@@ -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) =>

6
src/functions/randomInRange.ts
View File

@@ -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]

9
src/functions/removeFromArrayByKeyValue.ts
View File

@@ -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

6
src/functions/removeObjectProperty.ts
View File

@@ -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

17
src/functions/replaceFromArrayByKeyValue.ts
View File

@@ -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 };

6
src/functions/splitIntoChuks.ts
View File

@@ -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