@splendidlabz/utils 1.3.0

package/lib/objects/mix/mix.md

@@ -0,0 +1,78 @@
+# Mix
+
+- Merges objects. Like `Object.assign`, but performs a deep merge so won't be any mutation.
+- [Why I created `mix`](https://zellwk.com/blog/copy-properties-of-one-object-to-another-object)
+
+## Usage
+
+Import the module and use it.
+
+```js
+import mix from '@zellwk/javascript/mix'
+mix(target, source)
+```
+
+## Example
+
+Pass objects into mix to combine them. Mix creates a new object for you automatically. Nothing will get mutated.
+
+```js
+let count = 0
+const one = { one: 'one' }
+const two = { two: 'two' }
+const mixed = mix(one, two)
+
+// Output
+// {
+//   one: 'one',
+//   two: 'two',
+// }
+```
+
+## Features
+
+1. It copies accessors.
+2. It performs a deep merge so no mutation can happen
+
+### Copying accessors
+
+Mix copies accessors along with other properties. Most other deep merging libraries don't do this. `Object.assign` doesn't do this either.
+
+```js
+let count = 0
+const one = { one: 'one' }
+const two = { two: 'two' }
+const three = {
+  get count () {
+    return count
+  },
+  set count (value) {
+    count = value
+  }
+}
+const mixed = mix({}, one, two, three)
+
+// Output
+// {
+//   one: 'one',
+//   two: 'two',
+//   get count () { return count } ,
+//   set count (value) { count = value }
+// }
+```
+
+### Deep Merging
+
+`mix` copies nested objects and arrays so you don't have to worry about mutation.
+
+```js
+const one = {}
+const two = { nested: { value: 'two' } }
+const three = mix(one, two)
+
+// Nested values do not get mutated
+three.nested.value = 'three'
+console.log(two.nested.value) // 'two'
+```
+
+That's it!

package/lib/objects/mix/mix.test.js

@@ -0,0 +1,324 @@
+import { expect, it } from 'vitest'
+
+import { mix } from './mix.js'
+
+it('Merge objects', () => {
+  const one = { one: 'one', overwrite: 'nope' }
+  const two = { two: 'two', overwrite: 'yes' }
+  const three = mix(one, two)
+
+  expect(three).toEqual({
+    one: 'one',
+    two: 'two',
+    overwrite: 'yes',
+  })
+})
+
+it('Empty + Nested', () => {
+  const one = {}
+  const two = {
+    nested: {
+      value: 'nested-two',
+      deep: {
+        value: 'deep-two',
+      },
+    },
+  }
+  const three = mix(one, two)
+
+  expect(three).toEqual(two)
+  expect(three.nested.value).toBe('nested-two')
+  expect(three.nested.deep.value).toBe('deep-two')
+
+  // Prevents mutation of nested object
+  three.nested.value = 'three'
+  expect(two.nested.value).toBe('nested-two')
+
+  // Prevents mutation of deeply nested object
+  three.nested.deep.value = 'deep-three'
+  expect(two.nested.deep.value).toBe('deep-two')
+})
+
+it('Double Nested Objects', () => {
+  const one = {
+    one: 'one',
+    nested: {
+      one: 'nested-one',
+      deep: {
+        one: 'deep-one',
+      },
+    },
+  }
+
+  const two = {
+    two: 'two',
+    nested: {
+      two: 'nested-two',
+      deep: {
+        two: 'deep-two',
+      },
+    },
+  }
+
+  const three = mix(one, two)
+
+  expect(three.one).toBe('one')
+  expect(three.two).toBe('two')
+  expect(three.nested.one).toBe('nested-one')
+  expect(three.nested.two).toBe('nested-two')
+  expect(three.nested.deep.one).toBe('deep-one')
+  expect(three.nested.deep.two).toBe('deep-two')
+})
+
+it('Accessors', () => {
+  let count = 0
+  const one = {}
+  const two = {
+    get count() {
+      return count
+    },
+    set count(value) {
+      count = value
+    },
+  }
+
+  const three = mix(one, two)
+  expect(three).toEqual(two)
+
+  const propertyDescriptor = Object.getOwnPropertyDescriptor(three, 'count')
+  three.count = 3
+  expect(three.count).toBe(3)
+  expect(typeof propertyDescriptor.get).toBe('function')
+  expect(typeof propertyDescriptor.set).toBe('function')
+  expect(two.count !== three.count)
+})
+
+it('Empty + Nested accessors', () => {
+  let count = 0
+  const one = {}
+  const two = {
+    nested: {
+      get count() {
+        return count
+      },
+      set count(value) {
+        count = value
+      },
+    },
+  }
+
+  const three = mix(one, two)
+  expect(three).toEqual(two)
+  expect(two.nested).not.toBe(three.nested)
+
+  const descriptor = Object.getOwnPropertyDescriptor(three.nested, 'count')
+  expect(typeof descriptor.get).toBe('function')
+  expect(typeof descriptor.set).toBe('function')
+})
+
+it('Double nested with Accessors', () => {
+  let count = 0
+  const one = {
+    nested: {
+      get accessOne() {
+        return count
+      },
+      set accessOne(value) {
+        count = value
+      },
+    },
+  }
+  const two = {
+    nested: {
+      get accessTwo() {
+        return count
+      },
+      set accessTwo(value) {
+        count = value
+      },
+    },
+  }
+
+  const three = mix(one, two)
+  expect(one.nested).not.toBe(three.nested)
+  expect(two.nested).not.toBe(three.nested)
+
+  const accessOne = Object.getOwnPropertyDescriptor(three.nested, 'accessOne')
+  const accessTwo = Object.getOwnPropertyDescriptor(three.nested, 'accessTwo')
+
+  expect(typeof accessOne.get).toBe('function')
+  expect(typeof accessOne.set).toBe('function')
+  expect(typeof accessTwo.get).toBe('function')
+  expect(typeof accessTwo.set).toBe('function')
+})
+
+it('Nested arrays', () => {
+  const one = {}
+  const two = { array: [1, 2, 3] }
+  const three = mix(one, two)
+
+  expect(three).toEqual(two)
+  expect(typeof three.array.push).toBe('function')
+
+  // Prevent mutation
+  three.array.push(4)
+  expect(two.array).toHaveLength(3)
+  expect(three.array).toHaveLength(4)
+})
+
+it('Double objects with nested same array', () => {
+  const one = {
+    array: [1, 2, 3],
+  }
+  const two = {
+    array: [4, 5, 6],
+  }
+
+  const three = mix(one, two)
+  expect(typeof three.array.push).toBe('function')
+  expect(three.array).toHaveLength(6)
+})
+
+it('Objects in Arrays', () => {
+  const one = {}
+  const two = {
+    array: [
+      1,
+      { value: 2 },
+      3,
+      {
+        get count() {
+          return 1
+        },
+      },
+    ],
+  }
+  const three = mix(one, two)
+
+  expect(three).toEqual(two)
+  expect(typeof three.array.push).toBe('function')
+  expect(two.array[1]).not.toBe(three.array[1])
+
+  // Ensures accessors are copied over
+  const descriptor = Object.getOwnPropertyDescriptor(three.array[3], 'count')
+  expect(typeof descriptor.get).toBe('function')
+})
+
+it('Deep nested arrays', () => {
+  const one = {}
+  const two = {
+    array: [1, [2], 3],
+  }
+  const three = mix(one, two)
+
+  expect(three).toEqual(two)
+  expect(three.array).toHaveLength(3)
+  expect(three.array[1]).toHaveLength(1)
+  expect(two.array[1]).not.toBe(three.array[1])
+})
+
+it('Functions (cannot be cloned)', () => {
+  const one = {}
+  const two = {
+    nested: {
+      identity(i) {
+        return i
+      },
+      deep: {
+        identity(i) {
+          return i
+        },
+      },
+    },
+  }
+
+  const three = mix(one, two)
+  expect(three).toEqual(two)
+  expect(three.nested.identity).toBe(two.nested.identity)
+  expect(three.nested.deep.identity).toBe(two.nested.deep.identity)
+})
+
+it('Nested Dates', () => {
+  const one = {}
+  const two = {
+    date: new Date(),
+    nested: {
+      date: new Date(),
+    },
+  }
+  const three = mix(one, two)
+
+  expect(three.date).not.toBe(two.date)
+  expect(three.date.getTime()).toBe(two.date.getTime())
+  expect(three.nested.date).not.toBe(two.nested.date)
+})
+
+it('Nested Maps', () => {
+  const one = {}
+  const two = {
+    map: new Map(),
+    nested: {
+      map: new Map(),
+    },
+  }
+  const a = { one: 1 }
+  const b = { two: 2 }
+  two.map.set('item', { one: 1 })
+  two.map.set(a, b)
+  two.nested.map.set('item', { one: 1 })
+
+  const three = mix(one, two)
+
+  expect(three.map).not.toBe(two.map)
+  expect(three.map).toEqual(two.map)
+  expect(three.map.get('item')).toEqual({ one: 1 })
+  expect(three.map.get('item')).not.toBe(two.map.get('item'))
+
+  expect(three.nested.map).toEqual(two.nested.map)
+  expect(three.nested.map).not.toBe(two.nested.map)
+
+  expect(three.map.get(a)).toEqual(b)
+  expect(three.map.get(a)).not.toBe(two.map.get(a))
+
+  // Note: WeakMap keys are not enumerable... so they cannot be cloned.
+  // That's why we're not testing WeakMap
+})
+
+it('Nested Sets', () => {
+  const one = {}
+  const two = {
+    set: new Set(),
+    nested: {
+      set: new Set(),
+    },
+  }
+  const a = { object: 'test' }
+  two.set.add('one')
+  two.set.add(a)
+  two.nested.set.add('nested')
+
+  const three = mix(one, two)
+
+  expect(three.set).not.toBe(two.set)
+  expect(three.set).toEqual(two.set)
+  expect(three.set.has('one')).toBe(true)
+  expect(three.set.has(a)).toBe(false)
+
+  expect(three.nested.set).not.toBe(two.nested.set)
+  expect(three.nested.set).toEqual(two.nested.set)
+  expect(three.nested.set.has('nested')).toBe(true)
+
+  // Note: WeakSet contains objects only... so there's no point creating a deep clone. You won't be able to access them.
+  // That's why we're not testing WeakSet
+})
+
+// Prevents Prototype Pollution
+// https://codeburst.io/what-is-prototype-pollution-49482fc4b638
+it('Safe Merge', () => {
+  const polluted = JSON.parse('{"__proto__": {"admin": true}}')
+  const mixed = mix(polluted)
+
+  /* eslint-disable */
+  expect(mixed.__proto__).toEqual({})
+  /* eslint-enable */
+})

package/lib/objects/nested-property.js

@@ -0,0 +1,36 @@
+/**
+ * Returns the value at the given path in the object.
+ * If the path does not exist, it returns undefined.
+ *
+ * @param {Object} object - The object to get the nested property from.
+ * @param {Array} pathArr - The array representing the path to the property.
+ * @return {*} The value at the given path in the object or undefined if the path does not exist.
+ *
+ * @example
+ * let object = {
+ *   one: {
+ *     two: {
+ *       three: "value"
+ *     }
+ *   }
+ * };
+ * let path = ['one', 'two', 'three'];
+ * console.log(getNestedProperty(object, path)); // Outputs: "value"
+ */
+
+// Array syntax
+export function getNestedProperty(object, pathArr) {
+  return pathArr.reduce(
+    (nestedObject, key) =>
+      nestedObject && nestedObject[key] !== 'undefined'
+        ? nestedObject[key]
+        : undefined,
+    object,
+  )
+}
+
+// Dot syntax
+export function getNestedProperty2(object, path) {
+  const pathArray = path.split('.')
+  return getNestedProperty(object, pathArray)
+}

package/lib/objects/normalize-object.js

@@ -0,0 +1,10 @@
+import { pipe } from '../functions/functional.js'
+import { camelCaseKeys } from './camelcase-keys.js'
+import { omitEmpty } from './omit-empty.js'
+
+// Deprecated. Should remove.
+// Not using anymore.
+// Because snake_case is quite common.
+export function normalizeObject(object) {
+  return pipe(omitEmpty, camelCaseKeys)(object)
+}

package/lib/objects/omit-empty.js

@@ -0,0 +1,23 @@
+// Written by Claude AI and tested.
+export function omitEmpty(obj, shallow = false) {
+  if (typeof obj !== 'object' || obj === null) return obj
+  if (obj instanceof Date) return obj
+
+  const result = Array.isArray(obj) ? [] : {}
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (
+      value === null ||
+      value === undefined ||
+      value === '' ||
+      (typeof value === 'object' &&
+        !(value instanceof Date) &&
+        Object.keys(value).length === 0)
+    ) {
+      continue
+    }
+    result[key] = shallow ? value : omitEmpty(value)
+  }
+
+  return result
+}

package/lib/objects/omit-empty.test.js

@@ -0,0 +1,85 @@
+import { expect, it } from 'vitest'
+
+import { omitEmpty } from './omit-empty'
+
+it('Omit Empty Basic', ctx => {
+  const date = new Date()
+  const object = {
+    // Should not be omitted
+    a: { one: 1 },
+    b: [1],
+    c: 1,
+    d: 0,
+    e: 'string',
+    k: date,
+    l: false,
+
+    // Should be omitted
+    f: {},
+    g: [],
+    h: '',
+    i: null,
+    j: undefined,
+  }
+
+  const expected = {
+    a: { one: 1 },
+    b: [1],
+    c: 1,
+    d: 0,
+    e: 'string',
+    k: date,
+    l: false,
+  }
+
+  const result = omitEmpty(object)
+  expect(result).toEqual(expected)
+})
+
+it('Omit Empty Nested', ctx => {
+  const object = {
+    a: {
+      one: {},
+      two: [],
+      three: 1,
+      four: 'string',
+    },
+  }
+
+  const expected = {
+    a: {
+      three: 1,
+      four: 'string',
+    },
+  }
+
+  const result = omitEmpty(object)
+  expect(result).toEqual(expected)
+})
+
+it('Omit Empty Recursive', ctx => {
+  const object = {
+    a: {
+      one: {},
+      two: [],
+      three: {
+        alpha: {},
+        beta: [],
+        tetha: 1,
+        gamma: 'string',
+      },
+    },
+  }
+
+  const expected = {
+    a: {
+      three: {
+        tetha: 1,
+        gamma: 'string',
+      },
+    },
+  }
+
+  const result = omitEmpty(object)
+  expect(result).toEqual(expected)
+})

package/lib/objects/size.js

@@ -0,0 +1,41 @@
+// https://gist.github.com/rajinwonderland/36887887b8a8f12063f1d672e318e12e
+export function sizeOf(obj) {
+  let bytes = 0
+
+  function size(obj) {
+    if (obj !== null && obj !== undefined) {
+      switch (typeof obj) {
+        case 'number':
+          bytes += 8
+          break
+        case 'string':
+          bytes += obj.length * 2
+          break
+        case 'boolean':
+          bytes += 4
+          break
+        case 'object':
+          // eslint-disable-next-line no-case-declarations
+          const objClass = Object.prototype.toString.call(obj).slice(8, -1)
+          if (objClass === 'Object' || objClass === 'Array') {
+            for (const key in obj) {
+              // eslint-disable-next-line no-prototype-builtins
+              if (!obj.hasOwnProperty(key)) continue
+              size(obj[key])
+            }
+          } else bytes += obj.toString().length * 2
+          break
+      }
+    }
+    return bytes
+  }
+
+  function formatByteSize(bytes) {
+    if (bytes < 1024) return bytes + ' bytes'
+    else if (bytes < 1048576) return (bytes / 1024).toFixed(3) + ' KiB'
+    else if (bytes < 1073741824) return (bytes / 1048576).toFixed(3) + ' MiB'
+    else return (bytes / 1073741824).toFixed(3) + ' GiB'
+  }
+
+  return formatByteSize(size(obj))
+}

package/lib/objects/split.js

@@ -0,0 +1,19 @@
+/**
+ * Split on object up based on the keys provided.
+ * @param {Object} obj
+ * @param {Array} keys
+ * @returns
+ */
+export function splitObject(obj, keys) {
+  const picked = {}
+  const omitted = { ...obj }
+
+  keys.forEach(key => {
+    if (key in obj) {
+      picked[key] = obj[key]
+      delete omitted[key]
+    }
+  })
+
+  return { picked, omitted }
+}

package/lib/promises/index.js

@@ -0,0 +1 @@
+export * from './reject.js'

package/lib/promises/reject.js

@@ -0,0 +1,17 @@
+import statuses from 'statuses'
+import { omitEmpty } from '../objects/omit-empty.js'
+
+// Rejects a promise with HTTP Status Code
+export function reject(props, { includeStack = true } = {}) {
+  const { status, statusText, body, message } = props
+  const e = new Error()
+  const err = {
+    status,
+    statusText: statusText || (status && statuses(status)),
+    body,
+    message,
+    stack: includeStack && e.stack,
+  }
+
+  return Promise.reject(omitEmpty(err))
+}