add more docs

Author: vladkens

readme.md

@@ -104,11 +104,78 @@ toggleItem([1, 2, 3], 3)
 ```typescript
 import { updateByKey } from "array-utils-ts"
 
-const arr = [{ id: 1 }, { id: 2 }]
+// prettier-ignore
+const arr1 = [{ id: 1, v: 1 }, { id: 2, v: 1 }]
 
-updateByKey([1, 2, 3], 4)
-// -> [1, 2, 3, 4]
+const arr2 = updateByKey(arr1, "id", { id: 1, v: 2 })
+// -> [{ id: 1, v: 2 }, { id: 2, v: 1 }]
+// arr1 !== arr2
 
-updateByKey([1, 2, 3], 3)
-// -> [1, 2]
+const arr3 = updateByKey(arr2, "id", { id: 3, v: 1 })
+// -> [{ id: 1, v: 2 }, { id: 2, v: 1 }]
+// arr2 === arr3 // note: item not found, nothing changed
+```
+
+### upsertByKey
+
+```typescript
+import { upsertByKey } from "array-utils-ts"
+
+// prettier-ignore
+const arr1 = [{ id: 1, v: 1 }, { id: 2, v: 1 }]
+
+const arr2 = upsertByKey(arr1, "id", { id: 1, v: 2 })
+// -> [{ id: 1, v: 2 }, { id: 2, v: 1 }]
+// arr1 !== arr2
+
+const arr3 = upsertByKey(arr2, "id", { id: 3, v: 1 })
+// -> [{ id: 1, v: 2 }, { id: 2, v: 1 }, { id: 3, v: 1 }]
+// arr2 !== arr3
+```
+
+### toggleByKey
+
+```typescript
+import { toggleByKey } from "array-utils-ts"
+
+// prettier-ignore
+const arr1 = [{ id: 1, v: 1 }, { id: 2, v: 1 }]
+
+const arr2 = toggleByKey(arr1, "id", { id: 1, v: 2 })
+// -> [{ id: 2, v: 1 }]
+// arr1 !== arr2
+
+const arr3 = toggleByKey(arr2, "id", { id: 3, v: 1 })
+// -> [{ id: 2, v: 1 }, { id: 3, v: 1 }]
+// arr2 !== arr3
+```
+
+### isFirstByKey
+
+```typescript
+import { isFirstByKey } from "array-utils-ts"
+
+// prettier-ignore
+const arr = [{ id: 1, v: 1 }, { id: 2, v: 1 }]
+
+isFirstByKey(arr, "id", { id: 1, v: 2 })
+// -> true
+
+isFirstByKey(arr, "id", { id: 2, v: 1 })
+// -> false
+```
+
+### isLastByKey
+
+```typescript
+import { isLastByKey } from "array-utils-ts"
+
+// prettier-ignore
+const arr = [{ id: 1, v: 1 }, { id: 2, v: 1 }]
+
+isLastByKey(arr, "id", { id: 1, v: 1 })
+// -> false
+
+isLastByKey(arr, "id", { id: 2, v: 1 })
+// -> true
 ```

src/main.ts

@@ -2,9 +2,9 @@ type NotNullable<T> = Exclude<T, null | undefined>
 type NotEmpty<T> = Exclude<T, null | undefined | "">
 type Dict = Record<string, any>
 
-export const uniq = <T>(arr: T[]): T[] => {
-  return Array.from(new Set(arr))
-}
+// export const uniq = <T>(arr: T[]): T[] => {
+//   return Array.from(new Set(arr))
+// }
 
 export const filterNullable = <T>(items: T[]): NotNullable<T>[] => {
   return items.filter((x): x is NotNullable<T> => x !== undefined && x !== null)
@@ -28,27 +28,27 @@ export const toggleItem = <T>(arr: T[], item: T): T[] => {
 
 // By Key
 
-export const updateByKey = <T extends Dict>(arr: T[], key: keyof T, val: T): T[] => {
-  if (!arr.map((x) => x[key]).includes(val[key])) return arr
-  return arr.map((x) => (x[key] === val[key] ? { ...x, ...val } : x))
+export const updateByKey = <T extends Dict>(arr: T[], key: keyof T, obj: T): T[] => {
+  if (!arr.map((x) => x[key]).includes(obj[key])) return arr
+  return arr.map((x) => (x[key] === obj[key] ? { ...x, ...obj } : x))
 }
 
-export const upsertByKey = <T extends Dict>(arr: T[], key: keyof T, val: T): T[] => {
-  if (arr.map((x) => x[key]).includes(val[key])) {
-    return arr.map((x) => (x[key] === val[key] ? { ...x, ...val } : x))
+export const upsertByKey = <T extends Dict>(arr: T[], key: keyof T, obj: T): T[] => {
+  if (arr.map((x) => x[key]).includes(obj[key])) {
+    return arr.map((x) => (x[key] === obj[key] ? { ...x, ...obj } : x))
   }
-  return [...arr, val]
+  return [...arr, obj]
 }
 
-export const toggleByKey = <T extends Dict>(arr: T[], key: keyof T, val: T) => {
+export const toggleByKey = <T extends Dict>(arr: T[], key: keyof T, obj: T) => {
   const ids = arr.map((x) => x[key])
-  return ids.includes(val[key]) ? arr.filter((x) => x[key] !== val[key]) : [...arr, val]
+  return ids.includes(obj[key]) ? arr.filter((x) => x[key] !== obj[key]) : [...arr, obj]
 }
 
-export const isFirstByKey = <T extends Dict>(arr: T[], key: keyof T, val: T): boolean => {
-  return arr.findIndex((x) => x[key] === val[key]) === 0
+export const isFirstByKey = <T extends Dict>(arr: T[], key: keyof T, obj: T): boolean => {
+  return arr.findIndex((x) => x[key] === obj[key]) === 0
 }
 
-export const isLastByKey = <T extends Dict>(arr: T[], key: keyof T, val: T): boolean => {
-  return arr.findIndex((x) => x[key] === val[key]) === arr.length - 1
+export const isLastByKey = <T extends Dict>(arr: T[], key: keyof T, obj: T): boolean => {
+  return arr.findIndex((x) => x[key] === obj[key]) === arr.length - 1
 }