@inglorious/utils 2.0.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "A set of general-purpose utility functions designed with functional programming principles in mind.",
   "author": "IceOnFire <antony.mistretta@gmail.com> (https://ingloriouscoderz.it)",
   "license": "MIT",
@@ -24,7 +24,7 @@
     "./*": "./src/*"
   },
   "files": [
-    "src/*"
+    "src"
   ],
   "publishConfig": {
     "access": "public"

package/src/data-structures/array.js

@@ -29,7 +29,17 @@ export function contains(arr, item) {
  * @returns {Array} - The original array or the value wrapped in a new array.
  */
 export function ensureArray(arr) {
-  return Array.isArray(arr) ? arr : [arr]
+  return isArray(arr) ? arr : [arr]
+}
+
+/**
+ * Checks if a value is an array.
+ * @param {*} arr - The value to check.
+ *
+ * @returns {boolean} True if the value is an array, false otherwise.
+ */
+export function isArray(arr) {
+  return Array.isArray(arr)
 }
 
 /**

package/src/data-structures/array.test.js

@@ -1,6 +1,15 @@
 import { expect, test } from "vitest"
 
-import { contains, ensureArray, max, min, pop, push, remove } from "./array.js"
+import {
+  contains,
+  ensureArray,
+  isArray,
+  max,
+  min,
+  pop,
+  push,
+  remove,
+} from "./array.js"
 
 test("it should check if an array contains a value", () => {
   const arr = [3, 2, 6, 1, 7, 4, 5]
@@ -38,6 +47,18 @@ test("it should wrap the value in an array if it is not an array", () => {
   expect(ensureArray(str)).toStrictEqual([str])
 })
 
+test("it should correctly identify an array", () => {
+  const arr = [1, "two", { three: 3 }]
+
+  expect(isArray(arr)).toBe(true)
+})
+
+test("it should correctly identify a non-array", () => {
+  const str = "hello"
+
+  expect(isArray(str)).toBe(false)
+})
+
 test("it should find the maximum value of an array", () => {
   const arr = [3, 2, 6, 1, 7, 4, 5]
   const expectedResult = 7

package/src/data-structures/object.js

@@ -3,6 +3,7 @@ const NEXT_LEVEL = 2
 
 /**
  * Creates a deep clone of the given object.
+ *
  * @param {Object} obj - The object to clone.
  * @returns {Object} A deep clone of the input object.
  */
@@ -12,6 +13,7 @@ export function clone(obj) {
 
 /**
  * Filters the properties of an object based on a callback function.
+ *
  * @param {Object} obj - The object to filter.
  * @param {Function} callback - A function that determines whether a property should be included.
  *                              Receives (key, value, obj) as arguments.
@@ -27,6 +29,7 @@ export function filter(obj, callback) {
 
 /**
  * Finds the first property in an object that satisfies the callback function.
+ *
  * @param {Object} obj - The object to search.
  * @param {Function} callback - A function that determines whether a property matches.
  *                              Receives (key, value, obj) as arguments.
@@ -40,6 +43,7 @@ export function find(obj, callback) {
 
 /**
  * Checks if a value is a plain object.
+ *
  * @param {*} obj - The value to check.
  * @returns {boolean} True if the value is a plain object, false otherwise.
  */
@@ -49,6 +53,7 @@ export function isObject(obj) {
 
 /**
  * Maps the properties of an object using a callback function.
+ *
  * @param {Object} obj - The object to map.
  * @param {Function} callback - A function that transforms each property.
  *                              Receives (key, value, obj) as arguments.
@@ -99,6 +104,7 @@ export function produce(baseState, recipe, ...args) {
 
 /**
  * Converts an object or array to a formatted string representation.
+ *
  * @param {*} obj - The object or array to convert.
  * @param {number} [indentationLevel=INITIAL_LEVEL] - The current indentation level (used for nested structures).
  * @returns {string} A string representation of the input object or array.

package/src/data-structures/objects.js

@@ -1,45 +1,92 @@
+import { isFunction } from "../functions/function.js"
+import { isArray } from "./array.js"
 import { isObject } from "./object.js"
 
 /**
- * Extends a target object by merging it with one or more source objects.
- * Performs a deep merge for nested objects and arrays.
+ * Creates a new object by deeply merging a target object with one or more source objects.
+ * This function is immutable; it does not modify the original `target` or `sources`.
+ * Nested objects are merged recursively.
+ * Arrays from a source object will overwrite arrays in the target object.
  *
- * @param {Object} target - The target object to extend.
+ * @param {Object} target - The base object.
  * @param {...Object} sources - The source objects to merge into the target object.
- * @returns {Object} - The extended target object.
+ * @returns {Object} - A new object containing the merged properties.
+ * @see {@link merge} for a mutable version.
  */
 export function extend(target, ...sources) {
-  return merge({}, target, ...sources)
+  return extendWith(undefined, target, ...sources)
 }
 
 /**
  * Merges multiple source objects into a target object.
- * Performs a deep merge for nested objects and arrays.
+ * This function is mutable; it modifies the `target` object in place.
+ * Nested objects are merged recursively.
+ * Arrays from a source object will overwrite arrays in the target object.
  *
  * @param {Object} target - The target object to merge into.
  * @param {...Object} sources - The source objects to merge from.
  * @returns {Object} - The merged target object.
+ * @see {@link extend} for an immutable version.
  */
 export function merge(target, ...sources) {
+  return mergeWith(undefined, target, ...sources)
+}
+
+/**
+ * Creates a new object by deeply merging a target object with one or more source objects,
+ * using a custom merger function to handle specific properties.
+ * This function is immutable.
+ *
+ * @param {Function} [merger] - A function to customize merging behavior. It receives `(targetValue, sourceValue)`. If it returns `undefined`, the default merge logic is used.
+ * @param {Object} target - The base object.
+ * @param {...Object} sources - The source objects to merge.
+ * @returns {Object} A new object with the merged properties.
+ */
+export function extendWith(merger, target, ...sources) {
+  return mergeWith(merger, {}, target, ...sources)
+}
+
+/**
+ * Merges multiple source objects into a target object, using a custom merger function.
+ * This function is mutable; it modifies the `target` object in place.
+ *
+ * @param {Function} [merger] - A function to customize merging behavior. It receives `(targetValue, sourceValue)`. If it returns `undefined`, the default merge logic is used.
+ * @param {Object} target - The target object to merge into.
+ * @param {...Object} sources - The source objects to merge from.
+ * @returns {Object} The merged target object.
+ */
+export function mergeWith(merger, target, ...sources) {
   return sources
     .filter((source) => source != null)
-    .reduce((acc, source) => deepMerge(acc, source), target)
+    .reduce((acc, source) => deepMerge(acc, source, merger), target)
 }
 
 /**
- * Recursively merges the properties of the source object into the target object.
+ * Recursively merges properties from a source object into a target object.
+ * This is a helper function for `merge` and `extend`.
  *
  * @param {Object} target - The target object to merge into.
  * @param {Object} source - The source object to merge from.
- * @returns {Object} - The merged target object.
+ * @param {Function} [merger] - An optional function to customize merging behavior for specific keys.
+ * @returns {Object} - The modified target object.
  */
-function deepMerge(target, source) {
+function deepMerge(target, source, merger) {
   for (const [key, value] of Object.entries(source)) {
-    if (Array.isArray(value) || isObject(value)) {
-      if (target[key] === undefined) {
-        target[key] = new value.__proto__.constructor()
+    if (isFunction(merger)) {
+      const mergedValue = merger(target[key], value)
+      if (mergedValue !== undefined) {
+        target[key] = mergedValue
+        continue
+      }
+    }
+
+    if (isArray(value)) {
+      target[key] = value
+    } else if (isObject(value)) {
+      if (!isObject(target[key])) {
+        target[key] = {}
       }
-      target[key] = deepMerge(target[key], value)
+      target[key] = deepMerge(target[key], value, merger)
     } else {
       target[key] = value
     }

package/src/data-structures/objects.test.js

@@ -1,6 +1,7 @@
 import { expect, test } from "vitest"
 
-import { extend, merge } from "./objects.js"
+import { isArray } from "./array.js"
+import { extend, extendWith, merge, mergeWith } from "./objects.js"
 
 test("it should extend an object with another, producing a new object as a result", () => {
   const obj1 = {
@@ -32,13 +33,13 @@ test("it should extend an object with another, producing a new object as a resul
     primitiveMerged: 3,
     primitiveAdded: 4,
     primitiveArrayKept: [1, 2],
-    primitiveArrayMerged: [5, 4],
+    primitiveArrayMerged: [5],
     primitiveArrayAdded: [6, 7],
     primitiveObjectKept: { a: 1 },
     primitiveObjectMerged: { b: 2, c: 4 },
     primitiveObjectAdded: { d: 4 },
     nestedArrayKept: [{ a: 1 }],
-    nestedArrayMerged: [{ b: 2, c: 3, d: 4 }],
+    nestedArrayMerged: [{ d: 4 }],
     nestedArrayAdded: [{ e: 5 }],
     nestedObjectKept: { a: { b: 2 } },
     nestedObjectMerged: { c: { d: 4, e: 5 } },
@@ -80,13 +81,13 @@ test("it should deep merge an two objects, changing the first object in place",
     primitiveMerged: 3,
     primitiveAdded: 4,
     primitiveArrayKept: [1, 2],
-    primitiveArrayMerged: [5, 4],
+    primitiveArrayMerged: [5],
     primitiveArrayAdded: [6, 7],
     primitiveObjectKept: { a: 1 },
     primitiveObjectMerged: { b: 2, c: 4 },
     primitiveObjectAdded: { d: 4 },
     nestedArrayKept: [{ a: 1 }],
-    nestedArrayMerged: [{ b: 2, c: 3, d: 4 }],
+    nestedArrayMerged: [{ d: 4 }],
     nestedArrayAdded: [{ e: 5 }],
     nestedObjectKept: { a: { b: 2 } },
     nestedObjectMerged: { c: { d: 4, e: 5 } },
@@ -97,3 +98,99 @@ test("it should deep merge an two objects, changing the first object in place",
   expect(result).toStrictEqual(expectedResult)
   expect(result).toBe(obj1)
 })
+
+test("it should extend an object with a custom merger, producing a new object", () => {
+  const obj1 = {
+    primitiveArrayMerged: [3, 4],
+    nestedArrayMerged: [{ b: 2, c: 3 }],
+    nestedObjectMerged: { c: { d: 4 } },
+  }
+  const obj2 = {
+    primitiveArrayMerged: [5],
+    nestedArrayMerged: [{ d: 4 }],
+    nestedObjectMerged: { c: { e: 5 } },
+  }
+
+  const merger = (targetValue, sourceValue) => {
+    if (isArray(targetValue) && isArray(sourceValue)) {
+      return targetValue.concat(sourceValue)
+    }
+    return undefined // Use default logic for non-arrays
+  }
+
+  const expectedResult = {
+    primitiveArrayMerged: [3, 4, 5], // Concatenated
+    nestedArrayMerged: [{ b: 2, c: 3 }, { d: 4 }], // Concatenated
+    nestedObjectMerged: { c: { d: 4, e: 5 } }, // Default deep merge
+  }
+
+  const result = extendWith(merger, obj1, obj2)
+  expect(result).toStrictEqual(expectedResult)
+  expect(result).not.toBe(obj1)
+})
+
+test("it should merge an object with a custom merger, changing the first object in place", () => {
+  const obj1 = {
+    primitiveArrayMerged: [3, 4],
+    nestedArrayMerged: [{ b: 2, c: 3 }],
+    nestedObjectMerged: { c: { d: 4 } },
+  }
+  const obj2 = {
+    primitiveArrayMerged: [5],
+    nestedArrayMerged: [{ d: 4 }],
+    nestedObjectMerged: { c: { e: 5 } },
+  }
+
+  const merger = (targetValue, sourceValue) => {
+    if (isArray(targetValue) && isArray(sourceValue)) {
+      return targetValue.concat(sourceValue)
+    }
+    return undefined // Use default logic for non-arrays
+  }
+
+  const expectedResult = {
+    primitiveArrayMerged: [3, 4, 5], // Concatenated
+    nestedArrayMerged: [{ b: 2, c: 3 }, { d: 4 }], // Concatenated
+    nestedObjectMerged: { c: { d: 4, e: 5 } }, // Default deep merge
+  }
+
+  const result = mergeWith(merger, obj1, obj2)
+  expect(result).toStrictEqual(expectedResult)
+  expect(result).toBe(obj1)
+})
+
+test("extendWith without a merger should behave like extend", () => {
+  const obj1 = { a: 1, b: { c: 2 }, d: [3] }
+  const obj2 = { a: 10, b: { d: 20 }, d: [30] }
+
+  const expected = {
+    a: 10,
+    b: { c: 2, d: 20 },
+    d: [30],
+  }
+
+  const result = extendWith(undefined, obj1, obj2)
+  expect(result).toStrictEqual(expected)
+  expect(result).not.toBe(obj1)
+
+  const extendResult = extend(obj1, obj2)
+  expect(result).toStrictEqual(extendResult)
+})
+
+test("mergeWith without a merger should behave like merge", () => {
+  const obj1 = { a: 1, b: { c: 2 }, d: [3] }
+  const obj2 = { a: 10, b: { d: 20 }, d: [30] }
+
+  const expected = {
+    a: 10,
+    b: { c: 2, d: 20 },
+    d: [30],
+  }
+
+  const result = mergeWith(undefined, obj1, obj2)
+  expect(result).toStrictEqual(expected)
+  expect(result).toBe(obj1)
+
+  const mergeResult = merge({ a: 1, b: { c: 2 }, d: [3] }, obj2)
+  expect(result).toStrictEqual(mergeResult)
+})

package/src/functions/function.js

@@ -0,0 +1,9 @@
+/**
+ * Checks if a value is a function.
+ *
+ * @param {*} func - The value to check.
+ * @returns {boolean} True if the value is a function, false otherwise.
+ */
+export function isFunction(func) {
+  return typeof func === "function"
+}

package/src/functions/function.test.js

@@ -0,0 +1,15 @@
+import { expect, test } from "vitest"
+
+import { isFunction } from "./function.js"
+
+test("it should correctly identify a function", () => {
+  const func = () => {}
+
+  expect(isFunction(func)).toBe(true)
+})
+
+test("it should correctly identify a non-function", () => {
+  const str = "hello"
+
+  expect(isFunction(str)).toBe(false)
+})