@splendidlabz/utils 1.11.2 → 1.11.4

package/src/lib/objects/mix/mix.js

@@ -1,191 +0,0 @@
-const DEFAULT_OPTIONS = { array: 'replace' } // Can be concat or replace
-
-/**
- * Deep merges multiple objects into a new object with intelligent handling of arrays and nested objects.
- *
- * @param {...Object} sources - Objects to merge. Null and undefined values are skipped.
- * @return {Object} A new object containing the merged properties from all sources.
- *
- * @example
- * const obj1 = { a: 1, b: { x: 10 } }
- * const obj2 = { b: { y: 20 }, c: 3 }
- * const result = mix(obj1, obj2)
- * // Returns: { a: 1, b: { x: 10, y: 20 }, c: 3 }
- */
-export const mix = createMix()
-export const concatMix = createMix({ array: 'concat' })
-
-/**
- * Creates a customized mix function with specific options for array handling.
- *
- * @param {Object} [userOptions={}] - Configuration options for the mix function.
- * @param {('replace'|'concat')} [userOptions.array='replace'] - How to handle array merging:
- *   - 'replace': Arrays from later sources completely replace arrays from earlier sources
- *   - 'concat': Arrays are concatenated together
- * @return {Function} A mix function configured with the provided options.
- *
- * @example
- * // Create mix function that concatenates arrays
- * const concatMix = createMix({ array: 'concat' })
- * const obj1 = { items: [1, 2] }
- * const obj2 = { items: [3, 4] }
- * const result = concatMix(obj1, obj2)
- * // Returns: { items: [1, 2, 3, 4] }
- *
- * @example
- * // Create mix function that replaces arrays (default behavior)
- * const replaceMix = createMix({ array: 'replace' })
- * const obj1 = { items: [1, 2] }
- * const obj2 = { items: [3, 4] }
- * const result = replaceMix(obj1, obj2)
- * // Returns: { items: [3, 4] }
- */
-export function createMix(userOptions = {}) {
-  const options = { ...DEFAULT_OPTIONS, ...userOptions }
-
-  function _mix(...sources) {
-    const result = {}
-    for (const source of sources) {
-      // Skip null or undefined sources
-      if (source == null) continue
-      merge(result, source, options)
-    }
-    return result
-  }
-
-  return _mix
-}
-
-/**
- * Recursively merges properties from input object into output object.
- * Handles property descriptors, prevents prototype pollution, and deep clones values.
- *
- * @param {Object} output - The target object to merge properties into.
- * @param {Object} input - The source object to merge properties from.
- * @param {Object} options - Merge options including array handling strategy.
- * @property {('replace'|'concat')} options.array - How to handle array merging.
- */
-function merge(output, input, options) {
-  const props = Object.keys(input)
-
-  for (const prop of props) {
-    // Prevents Prototype Pollution
-    if (prop === '__proto__') continue
-
-    const descriptor = Object.getOwnPropertyDescriptor(input, prop)
-    const value = descriptor.value
-    if (value) descriptor.value = cloneDescriptorValue(value)
-
-    // If don't have prop => Define property
-    if (!output[prop]) {
-      Object.defineProperty(output, prop, descriptor)
-      continue
-    }
-
-    // If have prop, but type is not object => Overwrite by redefining property
-    if (typeof output[prop] !== 'object') {
-      Object.defineProperty(output, prop, descriptor)
-      continue
-    }
-
-    // Incoming non-object (primitive/null) => always overwrite
-    if (descriptor.value == null || typeof descriptor.value !== 'object') {
-      Object.defineProperty(output, prop, descriptor)
-      continue
-    }
-
-    // If have prop, and incoming is Array => concat or replace
-    if (objectType(descriptor.value) === '[object Array]') {
-      output[prop] =
-        options.array === 'replace'
-          ? descriptor.value.slice()
-          : output[prop].concat(descriptor.value)
-      continue
-    }
-
-    // If have prop, but type is Object => Merge.
-    merge(output[prop], descriptor.value, options)
-
-    // Not sure if I have to deal with overwriting maps / dates. When it comes, I guess!
-  }
-}
-
-/**
- * Creates a deep clone of a property descriptor value.
- * Handles arrays, objects, dates, maps, sets, and other types appropriately.
- *
- * @param {*} value - The value to clone.
- * @return {*} A deep clone of the input value.
- * @property {Array} value - Cloned recursively with all elements deep cloned.
- * @property {Object} value - Cloned with all properties and descriptors preserved.
- * @property {Date} value - Cloned as new Date with same time value.
- * @property {Map} value - Cloned with all entries deep cloned.
- * @property {Set} value - Cloned with all entries deep cloned.
- */
-function cloneDescriptorValue(value) {
-  // Arrays
-  if (objectType(value) === '[object Array]') {
-    const array = []
-    for (let v of value) {
-      v = cloneDescriptorValue(v)
-      array.push(v)
-    }
-    return array
-  }
-
-  // Objects
-  if (objectType(value) === '[object Object]') {
-    const obj = {}
-    const props = Object.keys(value)
-    for (const prop of props) {
-      const descriptor = Object.getOwnPropertyDescriptor(value, prop)
-      if (descriptor.value)
-        descriptor.value = cloneDescriptorValue(descriptor.value)
-      Object.defineProperty(obj, prop, descriptor)
-    }
-    return obj
-  }
-
-  // Other Types of Objects
-  if (objectType(value) === '[object Date]') {
-    return new Date(value.getTime())
-  }
-
-  if (objectType(value) === '[object Map]') {
-    const map = new Map()
-    for (const entry of value) {
-      map.set(entry[0], cloneDescriptorValue(entry[1]))
-    }
-    return map
-  }
-
-  if (objectType(value) === '[object Set]') {
-    const set = new Set()
-    for (const entry of value.entries()) {
-      set.add(cloneDescriptorValue(entry[0]))
-    }
-    return set
-  }
-
-  // Types we don't need to clone or cannot clone.
-  // Examples:
-  // - Primitives don't need to clone
-  // - Functions cannot clone
-  return value
-}
-
-/**
- * Returns the precise object type of a value using Object.prototype.toString.
- *
- * @param {*} value - The value to get the type of.
- * @return {string} The object type string (e.g., '[object Array]', '[object Object]', '[object Date]').
- *
- * @example
- * objectType([]) // '[object Array]'
- * objectType({}) // '[object Object]'
- * objectType(new Date()) // '[object Date]'
- * objectType(null) // '[object Null]'
- */
-function objectType(value) {
-  return Object.prototype.toString.call(value)
-}

package/src/lib/objects/mix/mix.md

@@ -1,78 +0,0 @@
-# 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/src/lib/objects/mix/mix.test.js

@@ -1,445 +0,0 @@
-import { expect, it } from 'vitest'
-
-import { concatMix, createMix, 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(3)
-  expect(three.array).toEqual([4, 5, 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('concatMix: concatenates arrays', () => {
-  const one = {
-    array: [1, 2, 3],
-  }
-  const two = {
-    array: [4, 5, 6],
-  }
-
-  const three = concatMix(one, two)
-  expect(typeof three.array.push).toBe('function')
-  expect(three.array).toHaveLength(6)
-  expect(three.array).toEqual([1, 2, 3, 4, 5, 6])
-})
-
-it('concatMix: empty array concat', () => {
-  const one = {}
-  const two = { array: [1, 2, 3] }
-  const three = concatMix(one, two)
-
-  expect(three).toEqual(two)
-  expect(typeof three.array.push).toBe('function')
-  expect(three.array).toHaveLength(3)
-
-  // Prevent mutation
-  three.array.push(4)
-  expect(two.array).toHaveLength(3)
-  expect(three.array).toHaveLength(4)
-})
-
-it('concatMix: nested objects with concatenated arrays', () => {
-  const one = {
-    nested: {
-      items: [1, 2],
-      other: 'value1',
-    },
-  }
-  const two = {
-    nested: {
-      items: [3, 4],
-      other: 'value2',
-    },
-  }
-
-  const three = concatMix(one, two)
-  expect(three.nested.items).toEqual([1, 2, 3, 4])
-  expect(three.nested.other).toBe('value2')
-})
-
-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 */
-})
-
-it('should skip null and undefined sources', () => {
-  const obj1 = { a: 1 }
-  const obj2 = { b: 2 }
-  const expected = { a: 1, b: 2 }
-
-  expect(mix(obj1, null, obj2)).toEqual(expected)
-  expect(mix(null, obj1, obj2)).toEqual(expected)
-  expect(mix(obj1, obj2, null)).toEqual(expected)
-
-  expect(mix(obj1, undefined, obj2)).toEqual(expected)
-  expect(mix(undefined, obj1, obj2)).toEqual(expected)
-  expect(mix(obj1, obj2, undefined)).toEqual(expected)
-
-  expect(mix(null, obj1, undefined, obj2, null)).toEqual(expected)
-})
-
-it('should not skip null and false properties', () => {
-  const obj1 = { a: 1, b: 2, c: 3 }
-  const obj2 = { a: null, b: false, c: undefined }
-  const expected = { a: null, b: false, c: undefined }
-
-  expect(mix(obj1, obj2)).toEqual(expected)
-})
-
-it('Real Nested Example', () => {
-  const defaultOpts = {
-    transforms: {
-      extractFromFileName: { date: 'pubDate', slug: 'slug' },
-      setLatestDate: {
-        targetProperty: 'date',
-        sourceProperties: ['pubDate', 'updateDate'],
-      },
-      generateExcerpt: true,
-      stripFileNumbering: true,
-      stripMore: true,
-    },
-    sort: {
-      props: ['data.date', 'data.pubDate', 'data.title'],
-      reverse: true,
-    },
-    filter: 'published',
-  }
-
-  const newOptions = {
-    transforms: {
-      extractFromFileName: false,
-      generateExcerpt: false,
-      stripMore: false,
-      // stripFileNumbering: true,
-    },
-    sort: { props: ['filePath'], reverse: false },
-    filter: false,
-  }
-  const expected = {
-    transforms: {
-      setLatestDate: {
-        targetProperty: 'date',
-        sourceProperties: ['pubDate', 'updateDate'],
-      },
-      extractFromFileName: false,
-      generateExcerpt: false,
-      stripFileNumbering: true,
-      stripMore: false,
-    },
-    sort: { props: ['filePath'], reverse: false },
-    filter: false,
-  }
-
-  const mixReplace = createMix({ array: 'replace' })
-  expect(mixReplace(defaultOpts, newOptions)).toEqual(expected)
-})