@tim-code/my-util 0.5.3 → 0.5.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",

package/src/array.js

@@ -20,12 +20,38 @@ 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
 }
 
 // sorts undefined and null to the end if applicable

package/src/array.test.js

@@ -68,6 +68,98 @@ 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("ascending", () => {

package/src/object.js

@@ -135,16 +135,14 @@ export function deepMerge(target, ...sources) {
 }
 
 /**
- * Produces a deep merge of a deep copy of each source object. See deepCopy() and deepMerge() documentation for caveats.
+ * Merges a deep copy of each source object into target. See deepCopy() and deepMerge() documentation for caveats.
+ * @param {Object} target The target object that will receive the merged properties.
  * @param {...Object} sources The source objects whose properties will be merged into the returned object
  * @returns {Object}
  */
-export function deepMergeCopy(...sources) {
-  if (!sources.length) {
-    return {}
-  }
+export function deepMergeCopy(target, ...sources) {
   const copies = sources.map(deepCopy)
-  const result = deepMerge(...copies)
+  const result = deepMerge(target, ...copies)
   return result
 }
 

package/src/object.test.js

@@ -423,35 +423,70 @@ describe("deepMerge", () => {
 
 // --- deepMergeCopy ---
 describe("deepMergeCopy", () => {
-  it("deeply merges deep copies of sources", () => {
-    const s1 = { a: { b: 1 } }
-    const s2 = { a: { c: 2 } }
-    const merged = deepMergeCopy(s1, s2)
-    expect(merged).toEqual({ a: { b: 1, c: 2 } })
-    expect(merged).not.toBe(s1)
-    expect(merged).not.toBe(s2)
+  it("deeply merges deep copies of sources into the target", () => {
+    const target = { a: { b: 1 } }
+    const s1 = { a: { c: 2 } }
+    const s2 = { a: { d: 3 } }
+    const origTarget = JSON.stringify(target)
+    const merged = deepMergeCopy(target, s1, s2)
+    expect(merged).toEqual({ a: { b: 1, c: 2, d: 3 } })
+    expect(merged).toBe(target)
     expect(merged.a).not.toBe(s1.a)
     expect(merged.a).not.toBe(s2.a)
+    expect(JSON.stringify(target)).not.toBe(origTarget)
+    expect(s1).toEqual({ a: { c: 2 } })
+    expect(s2).toEqual({ a: { d: 3 } })
   })
 
   it("does not mutate source objects", () => {
-    const s1 = { a: 1 }
-    const s2 = { b: 2 }
+    const target = { a: 1 }
+    const s1 = { b: 2 }
+    const s2 = { c: 3 }
     const orig1 = JSON.stringify(s1)
     const orig2 = JSON.stringify(s2)
-    deepMergeCopy(s1, s2)
+    deepMergeCopy(target, s1, s2)
     expect(JSON.stringify(s1)).toBe(orig1)
     expect(JSON.stringify(s2)).toBe(orig2)
   })
 
-  it("handles arrays and primitives", () => {
-    const s1 = { a: [1, 2] }
-    const s2 = { a: [3, 4], b: 5 }
-    expect(deepMergeCopy(s1, s2)).toEqual({ a: [3, 4], b: 5 })
+  it("handles arrays and primitives in sources", () => {
+    const target = { a: [1, 2] }
+    const s1 = { a: [3, 4], b: 5 }
+    expect(deepMergeCopy(target, s1)).toEqual({ a: [3, 4], b: 5 })
   })
 
-  it("returns {} if called with no sources", () => {
-    expect(deepMergeCopy()).toEqual({})
+  it("returns the target object", () => {
+    const target = { x: 1 }
+    const s1 = { y: 2 }
+    expect(deepMergeCopy(target, s1)).toBe(target)
+  })
+
+  it("merges nothing if no sources provided (returns target as is)", () => {
+    const target = { foo: 1 }
+    expect(deepMergeCopy(target)).toBe(target)
+    expect(target).toEqual({ foo: 1 })
+  })
+
+  it("returns target if called with no arguments", () => {
+    expect(deepMergeCopy({})).toEqual({})
+    expect(deepMergeCopy()).toEqual(undefined)
+  })
+
+  it("does not mutate the target if no sources are provided", () => {
+    const target = { z: 9 }
+    const result = deepMergeCopy(target)
+    expect(result).toBe(target)
+    expect(result).toEqual({ z: 9 })
+  })
+
+  it("does not merge inherited properties from sources", () => {
+    const target = {}
+    const proto = { x: 1 }
+    const s1 = Object.create(proto)
+    s1.a = 2
+    deepMergeCopy(target, s1)
+    expect(target).toEqual({ a: 2 })
+    expect("x" in target).toBe(false)
   })
 })