@tim-code/my-util 0.5.4 → 0.5.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.5.4",
+  "version": "0.5.6",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",
@@ -28,8 +28,8 @@
     ]
   },
   "devDependencies": {
-    "@tim-code/eslint-config": "^1.3.3",
     "@jest/globals": "^29.7.0",
+    "@tim-code/eslint-config": "^1.3.3",
     "jest": "^29.7.0"
   },
   "jest": {
@@ -37,5 +37,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@tim-code/my-util": "^0.5.5"
   }
 }

package/src/array.js

@@ -20,12 +20,82 @@ export function chunk(array, chunkSize = array.length) {
 }
 
 /**
- * Shorthand for returning all unique elements in an array.
+ * Returns all unique elements in an array, or alternatively by checking a key's value or function's result.
  * @param {Array} array
+ * @param {Object} $1
+ * @param {string|number|Function=} $1.key
+ *  If a function, calls the provided function on an element to get the value to check for uniqueness.
+ *  If a string or number, checks each element's value at key for uniqueness.
  * @returns {Array}
  */
-export function unique(array) {
-  return [...new Set(array)]
+export function unique(array, { key } = {}) {
+  const seen = new Set()
+  const result = []
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = key(element, i, array)
+      if (!seen.has(value)) {
+        seen.add(value)
+        result.push(element)
+      }
+    }
+  } else if (typeof key === "string" || typeof key === "number") {
+    for (const element of array) {
+      const value = element[key]
+      if (!seen.has(value)) {
+        seen.add(value)
+        result.push(element)
+      }
+    }
+  } else {
+    return [...new Set(array)]
+  }
+  return result
+}
+
+/**
+ * Returns groups of duplicate elements in an array.
+ * Each group is an array of elements that share the same key or callback result.
+ * Only groups with more than one element are returned. Returns an empty array if no duplicates.
+ * @param {Array} array
+ * @param {Object} $1
+ * @param {string|number|Function=} $1.key
+ *  If a function, calls the provided function on an element to get the value for grouping.
+ *  If a string or number, uses element[key].
+ *  If omitted, compares elements directly.
+ * @returns {Array<Array>}
+ */
+export function duplicates(array, { key } = {}) {
+  const groups = new Map()
+
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = key(element, i, array)
+      if (!groups.has(value)) {
+        groups.set(value, [])
+      }
+      groups.get(value).push(element)
+    }
+  } else if (typeof key === "string" || typeof key === "number") {
+    for (const element of array) {
+      const value = element[key]
+      if (!groups.has(value)) {
+        groups.set(value, [])
+      }
+      groups.get(value).push(element)
+    }
+  } else {
+    for (const element of array) {
+      if (!groups.has(element)) {
+        groups.set(element, [])
+      }
+      groups.get(element).push(element)
+    }
+  }
+  const results = [...groups.values()].filter((group) => group.length > 1)
+  return results
 }
 
 // sorts undefined and null to the end if applicable

package/src/array.test.js

@@ -1,7 +1,9 @@
 /* eslint-disable no-restricted-syntax */
 import { describe, expect, it, jest } from "@jest/globals"
 
-const { chunk, unique, ascending, descending, multilevel } = await import("./array.js")
+const { chunk, unique, duplicates, ascending, descending, multilevel } = await import(
+  "./array.js"
+)
 
 describe("chunk", () => {
   it("splits array into chunks of specified size", () => {
@@ -68,6 +70,261 @@ describe("unique", () => {
     const b = {}
     expect(unique([a, b, a])).toEqual([a, b])
   })
+
+  it("returns unique elements by key (string)", () => {
+    const arr = [
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 1, name: "c" },
+      { id: 3, name: "d" },
+      { id: 2, name: "e" },
+    ]
+    expect(unique(arr, { key: "id" })).toEqual([
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 3, name: "d" },
+    ])
+  })
+
+  it("returns unique elements by key (number)", () => {
+    const arr = [
+      { 0: "a", v: 1 },
+      { 0: "b", v: 2 },
+      { 0: "a", v: 3 },
+      { 0: "c", v: 4 },
+    ]
+    expect(unique(arr, { key: 0 })).toEqual([
+      { 0: "a", v: 1 },
+      { 0: "b", v: 2 },
+      { 0: "c", v: 4 },
+    ])
+  })
+
+  it("returns unique elements by function", () => {
+    const arr = [
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 1, name: "c" },
+      { id: 3, name: "d" },
+      { id: 2, name: "e" },
+    ]
+    expect(
+      unique(arr, {
+        key: (el) => el.id % 2, // group by odd/even id
+      })
+    ).toEqual([
+      { id: 1, name: "a" }, // id % 2 === 1
+      { id: 2, name: "b" }, // id % 2 === 0
+    ])
+  })
+
+  it("returns unique elements by function using index and array", () => {
+    const arr = ["a", "b", "c", "a"]
+    expect(
+      unique(arr, {
+        key: (el, i, array) => array.indexOf(el), // only first occurrence is unique
+      })
+    ).toEqual(["a", "b", "c"])
+  })
+
+  it("returns unique elements by key when some elements lack the key", () => {
+    const arr = [{ id: 1 }, {}, { id: 1 }, { id: 2 }, {}]
+    expect(unique(arr, { key: "id" })).toEqual([{ id: 1 }, {}, { id: 2 }])
+  })
+
+  it("returns unique elements by function when function returns undefined/null", () => {
+    const arr = [{ id: 1 }, {}, { id: 2 }, { id: null }, {}]
+    expect(
+      unique(arr, {
+        key: (el) => el.id,
+      })
+    ).toEqual([{ id: 1 }, {}, { id: 2 }, { id: null }])
+  })
+
+  it("returns unique elements by key when key value is undefined/null", () => {
+    const arr = [{ id: 1 }, { id: undefined }, { id: 2 }, { id: null }, { id: undefined }]
+    expect(unique(arr, { key: "id" })).toEqual([
+      { id: 1 },
+      { id: undefined },
+      { id: 2 },
+      { id: null },
+    ])
+  })
+
+  it("returns unique elements for primitive array if key is not provided", () => {
+    expect(unique([1, 2, 2, 3], {})).toEqual([1, 2, 3])
+    expect(unique([1, 2, 2, 3], { key: undefined })).toEqual([1, 2, 3])
+  })
+
+  it("returns unique elements for object array if key is not provided", () => {
+    const a = { x: 1 }
+    const b = { x: 2 }
+    expect(unique([a, b, a], {})).toEqual([a, b])
+    expect(unique([a, b, a], { key: undefined })).toEqual([a, b])
+  })
+})
+
+describe("duplicates", () => {
+  it("returns empty array if there are no duplicates", () => {
+    expect(duplicates([1, 2, 3])).toEqual([])
+    expect(duplicates([], {})).toEqual([])
+  })
+
+  it("returns groups of duplicate primitives", () => {
+    expect(duplicates([1, 2, 1, 3, 2, 1])).toEqual([
+      [1, 1, 1],
+      [2, 2],
+    ])
+    expect(duplicates(["a", "b", "a", "c", "b"])).toEqual([
+      ["a", "a"],
+      ["b", "b"],
+    ])
+  })
+
+  it("returns groups of duplicate objects by reference", () => {
+    const a = {}
+    const b = {}
+    expect(duplicates([a, b, a, b, a])).toEqual([
+      [a, a, a],
+      [b, b],
+    ])
+  })
+
+  it("returns groups of duplicates by key (string)", () => {
+    const arr = [
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 1, name: "c" },
+      { id: 3, name: "d" },
+      { id: 2, name: "e" },
+      { id: 1, name: "f" },
+    ]
+    expect(duplicates(arr, { key: "id" })).toEqual([
+      [
+        { id: 1, name: "a" },
+        { id: 1, name: "c" },
+        { id: 1, name: "f" },
+      ],
+      [
+        { id: 2, name: "b" },
+        { id: 2, name: "e" },
+      ],
+    ])
+  })
+
+  it("returns groups of duplicates by key (number)", () => {
+    const arr = [
+      { 0: "a", v: 1 },
+      { 0: "b", v: 2 },
+      { 0: "a", v: 3 },
+      { 0: "c", v: 4 },
+      { 0: "b", v: 5 },
+    ]
+    expect(duplicates(arr, { key: 0 })).toEqual([
+      [
+        { 0: "a", v: 1 },
+        { 0: "a", v: 3 },
+      ],
+      [
+        { 0: "b", v: 2 },
+        { 0: "b", v: 5 },
+      ],
+    ])
+  })
+
+  it("returns groups of duplicates by function", () => {
+    const arr = [
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 1, name: "c" },
+      { id: 3, name: "d" },
+      { id: 2, name: "e" },
+      { id: 1, name: "f" },
+    ]
+    expect(
+      duplicates(arr, {
+        key: (el) => el.id % 2, // group by odd/even id
+      })
+    ).toEqual([
+      [
+        { id: 1, name: "a" },
+        { id: 1, name: "c" },
+        { id: 3, name: "d" },
+        { id: 1, name: "f" },
+      ],
+      [
+        { id: 2, name: "b" },
+        { id: 2, name: "e" },
+      ],
+    ])
+  })
+
+  it("returns groups of duplicates by function using index and array", () => {
+    const arr = ["a", "b", "c", "a", "c"]
+    expect(
+      duplicates(arr, {
+        key: (el, i, array) => array.indexOf(el), // group by first occurrence index
+      })
+    ).toEqual([
+      ["a", "a"],
+      ["c", "c"],
+    ])
+  })
+
+  it("returns groups of duplicates by key when some elements lack the key", () => {
+    const arr = [{ id: 1 }, {}, { id: 1 }, { id: 2 }, {}, { id: 2 }]
+    expect(duplicates(arr, { key: "id" })).toEqual([
+      [{ id: 1 }, { id: 1 }],
+      [{}, {}],
+      [{ id: 2 }, { id: 2 }],
+    ])
+  })
+
+  it("returns groups of duplicates by function when function returns undefined/null", () => {
+    const arr = [{ id: 1 }, {}, { id: 2 }, { id: null }, {}, { id: null }]
+    expect(
+      duplicates(arr, {
+        key: (el) => el.id,
+      })
+    ).toEqual([
+      [{}, {}],
+      [{ id: null }, { id: null }],
+    ])
+  })
+
+  it("returns groups of duplicates by key when key value is undefined/null", () => {
+    const arr = [
+      { id: 1 },
+      { id: undefined },
+      { id: 2 },
+      { id: null },
+      { id: undefined },
+      { id: null },
+    ]
+    expect(duplicates(arr, { key: "id" })).toEqual([
+      [{ id: undefined }, { id: undefined }],
+      [{ id: null }, { id: null }],
+    ])
+  })
+
+  it("returns empty array if all elements are unique by key or function", () => {
+    const arr = [{ id: 1 }, { id: 2 }, { id: 3 }]
+    expect(duplicates(arr, { key: "id" })).toEqual([])
+    expect(
+      duplicates(arr, {
+        key: (el) => el.id,
+      })
+    ).toEqual([])
+  })
+
+  it("returns empty array for empty input with key or function", () => {
+    expect(duplicates([], { key: "id" })).toEqual([])
+    expect(
+      duplicates([], {
+        key: (el) => el,
+      })
+    ).toEqual([])
+  })
 })
 
 describe("ascending", () => {