@inglorious/utils 3.6.3 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inglorious/utils",
-  "version": "3.6.3",
+  "version": "3.7.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",

package/src/data-structures/object.js

@@ -2,16 +2,29 @@ import { v } from "../v.js"
 import { isArray } from "./array.js"
 
 const INITIAL_LEVEL = 0
+const LAST_KEY_OFFSET = 1
+const NEXT_KEY_OFFSET = 1
 const NEXT_LEVEL = 2
 
 /**
- * Creates a deep clone of the given object.
+ * Creates a deep clone of a given value using the structured clone algorithm.
+ * This is a modern and efficient way to deep-clone objects.
  *
- * @param {Object} obj - The object to clone.
- * @returns {Object} A deep clone of the input object.
+ * Note: `structuredClone` has some limitations. It cannot clone functions,
+ * DOM nodes, property descriptors, getters, setters, or certain other
+ * non-serializable objects. It will throw a `DataCloneError` in such cases.
+ *
+ * For more details, see:
+ * https://developer.mozilla.org/en-US/docs/Web/API/structuredClone
+ *
+ * This is similar to Lodash's `_.cloneDeep`.
+ *
+ * @template T
+ * @param {T} obj - The value to clone.
+ * @returns {T} A deep clone of the input value.
  */
 export function clone(obj) {
-  return deserialize(serialize(obj))
+  return structuredClone(obj)
 }
 
 /**
@@ -83,6 +96,42 @@ export function find(obj, callback) {
   ])
 }
 
+/**
+ * Gets the value at a specified path of an object. If the resolved value is
+ * `undefined`, the `defaultValue` is returned in its place. This function
+ * supports dot-notation for nested properties and numbers for array indices.
+ *
+ * This is similar to Lodash's `_.get`.
+ *
+ * @example
+ * const object = { 'a': [{ 'b': { 'c': 3 } }] };
+ * get(object, 'a.0.b.c');
+ * // => 3
+ *
+ * get(object, 'a.0.d', 'default');
+ * // => 'default'
+ *
+ * @param {Object} obj - The object to query.
+ * @param {string} path - The path of the property to retrieve.
+ * @param {*} [defaultValue=undefined] - The value returned for `undefined` resolved values.
+ * @returns {*} Returns the resolved value, else the `defaultValue`.
+ */
+export function get(obj, path, defaultValue = undefined) {
+  if (!path) return defaultValue
+
+  const keys = path.split(".")
+  let result = obj
+
+  for (const key of keys) {
+    if (result == null || typeof result !== "object") {
+      return defaultValue
+    }
+    result = result[key]
+  }
+
+  return result !== undefined ? result : defaultValue
+}
+
 /**
  * Checks if a value is a plain object.
  *
@@ -185,6 +234,50 @@ export function serialize(obj) {
   return JSON.stringify(obj, replacer)
 }
 
+/**
+ * Sets the value at a specified path of an object. If a portion of the path
+ * doesn't exist, it's created. Arrays are created for missing index properties
+ * while objects are created for all other missing properties. This function
+ * mutates the object.
+ *
+ * This is similar to Lodash's `_.set`.
+ *
+ * @example
+ * const object = { 'a': [{ 'b': { 'c': 3 } }] };
+ * set(object, 'a.0.b.d', 4);
+ * // object is now { 'a': [{ 'b': { 'c': 3, 'd': 4 } }] }
+ *
+ * set(object, 'x.0.y', 5);
+ * // object is now { 'a': [...], 'x': [{ 'y': 5 }] }
+ *
+ * @param {Object} obj - The object to modify.
+ * @param {string} path - The path of the property to set.
+ * @param {*} value - The value to set.
+ * @returns {Object} Returns the modified object.
+ */
+export function set(obj, path, value) {
+  if (!path) return obj
+
+  const keys = path.split(".")
+  let current = obj
+
+  for (let i = 0; i < keys.length - LAST_KEY_OFFSET; i++) {
+    const key = keys[i]
+    const nextKey = keys[i + NEXT_KEY_OFFSET]
+
+    // Create missing intermediate objects
+    if (!(key in current) || typeof current[key] !== "object") {
+      // Create array if next key is a number, object otherwise
+      current[key] = /^\d+$/.test(nextKey) ? [] : {}
+    }
+
+    current = current[key]
+  }
+
+  current[keys[keys.length - LAST_KEY_OFFSET]] = value
+  return obj
+}
+
 /**
  * Converts an object or array to a formatted string representation.
  *

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

@@ -6,10 +6,12 @@ import {
   deserialize,
   filter,
   find,
+  get,
   isObject,
   map,
   produce,
   serialize,
+  set,
   toString,
 } from "./object.js"
 
@@ -63,6 +65,62 @@ test("it should behave like Array.prototype.find, but on an object", () => {
   expect(find(obj, callback)).toStrictEqual(expectedResult)
 })
 
+test("get should retrieve a value from a nested object", () => {
+  const obj = { a: { b: { c: 1 } }, d: [{ e: 2 }] }
+
+  expect(get(obj, "a.b.c")).toBe(1)
+})
+
+test("get should retrieve a value from an array within an object", () => {
+  const obj = { a: { b: { c: 1 } }, d: [{ e: 2 }] }
+
+  expect(get(obj, "d.0.e")).toBe(2)
+})
+
+test("get should return a default value for a non-existent path", () => {
+  const obj = { a: { b: { c: 1 } } }
+
+  expect(get(obj, "a.x.y", "default")).toBe("default")
+})
+
+test("get should return undefined for a non-existent path without a default value", () => {
+  const obj = { a: { b: { c: 1 } } }
+
+  expect(get(obj, "a.x.y")).toBeUndefined()
+})
+
+test("get should handle null or undefined paths gracefully", () => {
+  const obj = { a: 1 }
+
+  expect(get(obj, null, "default")).toBe("default")
+  expect(get(obj, undefined, "default")).toBe("default")
+})
+
+test("set should modify a value at a given path", () => {
+  const obj = { a: { b: 1 } }
+  set(obj, "a.b", 2)
+  expect(obj.a.b).toBe(2)
+})
+
+test("set should create nested objects if they do not exist", () => {
+  const obj = {}
+  set(obj, "a.b.c", 3)
+  expect(obj).toStrictEqual({ a: { b: { c: 3 } } })
+})
+
+test("set should create nested arrays for numeric keys", () => {
+  const obj = {}
+  set(obj, "a.0.b", "value")
+  expect(obj).toStrictEqual({ a: [{ b: "value" }] })
+})
+
+test("set should return the mutated object", () => {
+  const obj = { a: 1 }
+  const result = set(obj, "b", 2)
+  expect(result).toBe(obj)
+  expect(result).toStrictEqual({ a: 1, b: 2 })
+})
+
 test("it correctly should check if a value is an object", () => {
   expect(isObject(1)).toBe(false)
   expect(isObject("a")).toBe(false)