@radio-garden/ditojs-utils 2.85.0-0.5067ad799

package/src/object/equals.test.js

@@ -0,0 +1,269 @@
+import { equals } from './equals.js'
+
+describe('equals()', () => {
+  const symbol1 = Symbol('a')
+  const symbol2 = Symbol('b')
+  describe.each([
+    [1, 1, true],
+    [1, Object(1), true],
+    [1, '1', false],
+    [1, 2, false],
+    [-0, -0, true],
+    [0, 0, true],
+    [0, Object(0), true],
+    [Object(0), Object(0), true],
+    [-0, 0, true],
+    [0, '0', false],
+    [0, null, false],
+
+    [NaN, NaN, true],
+    [NaN, Object(NaN), true],
+    [Object(NaN), Object(NaN), true],
+    [NaN, 'a', false],
+    [NaN, Infinity, false],
+
+    ['a', 'a', true],
+    ['a', Object('a'), true],
+    [Object('a'), Object('a'), true],
+    ['a', 'b', false],
+    ['a', ['a'], false],
+
+    [true, true, true],
+    [true, Object(true), true],
+    [Object(true), Object(true), true],
+    [true, 1, false],
+    [true, 'a', false],
+    [false, false, true],
+    [false, Object(false), true],
+    [Object(false), Object(false), true],
+    [false, 0, false],
+    [false, '', false],
+
+    [symbol1, symbol1, true],
+    [symbol1, Object(symbol1), true],
+    [Object(symbol1), Object(symbol1), true],
+    [symbol1, symbol2, false],
+
+    [null, null, true],
+    [null, undefined, false],
+    [null, {}, false],
+    [null, '', false],
+    [undefined, undefined, true],
+    [undefined, null, false],
+    [undefined, '', false]
+  ])(
+    'equals(%o, %o) (should compare primitives)',
+    (a, b, expected) => {
+      it(`returns ${expected}`, () => {
+        expect(equals(a, b)).toBe(expected)
+      })
+    }
+  )
+
+  it('should compare arrays', () => {
+    let array1 = [true, null, 1, 'a', undefined]
+    let array2 = [true, null, 1, 'a', undefined]
+
+    expect(equals(array1, array2)).toBe(true)
+
+    array1 = [[1, 2, 3], new Date(2012, 4, 23), /x/, { e: 1 }]
+    array2 = [[1, 2, 3], new Date(2012, 4, 23), /x/, { e: 1 }]
+
+    expect(equals(array1, array2)).toBe(true)
+
+    array1 = [1]
+    array1[2] = 3
+
+    array2 = [1]
+    array2[1] = undefined
+    array2[2] = 3
+
+    expect(equals(array1, array2)).toBe(true)
+
+    array1 = [
+      Object(1),
+      false,
+      Object('a'),
+      /x/,
+      new Date(2012, 4, 23),
+      ['a', 'b', [Object('c')]],
+      { a: 1 }
+    ]
+    array2 = [
+      1,
+      Object(false),
+      'a',
+      /x/,
+      new Date(2012, 4, 23),
+      ['a', Object('b'), ['c']],
+      { a: 1 }
+    ]
+
+    expect(equals(array1, array2)).toBe(true)
+
+    array1 = [1, 2, 3]
+    array2 = [3, 2, 1]
+
+    expect(equals(array1, array2)).toBe(false)
+
+    array1 = [1, 2]
+    array2 = [1, 2, 3]
+
+    expect(equals(array1, array2)).toBe(false)
+  })
+
+  it(`should treat arrays with identical values but different non-index properties as equal`, () => {
+    let array1 = [1, 2, 3]
+    let array2 = [1, 2, 3]
+
+    array1.every =
+      array1.filter =
+      array1.forEach =
+      array1.indexOf =
+      array1.lastIndexOf =
+      array1.map =
+      array1.some =
+      array1.reduce =
+      array1.reduceRight =
+        null
+
+    array2.concat =
+      array2.join =
+      array2.pop =
+      array2.reverse =
+      array2.shift =
+      array2.slice =
+      array2.sort =
+      array2.splice =
+      array2.unshift =
+        null
+
+    expect(equals(array1, array2)).toBe(true)
+
+    array1 = [1, 2, 3]
+    array1.a = 1
+
+    array2 = [1, 2, 3]
+    array2.b = 1
+
+    expect(equals(array1, array2)).toBe(true)
+
+    array1 = /c/.exec('abcde')
+    array2 = ['c']
+
+    expect(equals(array1, array2)).toBe(true)
+  })
+
+  it('should compare sparse arrays', () => {
+    const array = Array(1)
+    expect(equals(array, Array(1))).toBe(true)
+    expect(equals(array, [undefined])).toBe(true)
+    expect(equals(array, Array(2))).toBe(false)
+  })
+
+  it('should compare plain objects', () => {
+    let object1 = { a: true, b: null, c: 1, d: 'a', e: undefined }
+    let object2 = { a: true, b: null, c: 1, d: 'a', e: undefined }
+
+    expect(equals(object1, object2)).toBe(true)
+
+    object1 = { a: [1, 2, 3], b: new Date(2012, 4, 23), c: /x/, d: { e: 1 } }
+    object2 = { a: [1, 2, 3], b: new Date(2012, 4, 23), c: /x/, d: { e: 1 } }
+
+    expect(equals(object1, object2)).toBe(true)
+
+    object1 = { a: 1, b: 2, c: 3 }
+    object2 = { a: 3, b: 2, c: 1 }
+
+    expect(equals(object1, object2)).toBe(false)
+
+    object1 = { a: 1, b: 2, c: 3 }
+    object2 = { d: 1, e: 2, f: 3 }
+
+    expect(equals(object1, object2)).toBe(false)
+
+    object1 = { a: 1, b: 2 }
+    object2 = { a: 1, b: 2, c: 3 }
+
+    expect(equals(object1, object2)).toBe(false)
+  })
+
+  it('should compare objects regardless of key order', () => {
+    const object1 = { a: 1, b: 2, c: 3 }
+    const object2 = { c: 3, a: 1, b: 2 }
+
+    expect(equals(object1, object2)).toBe(true)
+  })
+
+  it('should compare nested objects', () => {
+    function noop() {}
+    const object1 = {
+      a: [1, 2, 3],
+      b: true,
+      c: Object(1),
+      d: 'a',
+      e: {
+        f: ['a', Object('b'), 'c'],
+        g: Object(false),
+        h: new Date(2012, 4, 23),
+        i: noop,
+        j: 'a'
+      }
+    }
+
+    const object2 = {
+      a: [1, Object(2), 3],
+      b: Object(true),
+      c: 1,
+      d: Object('a'),
+      e: {
+        f: ['a', 'b', 'c'],
+        g: false,
+        h: new Date(2012, 4, 23),
+        i: noop,
+        j: 'a'
+      }
+    }
+
+    expect(equals(object1, object2)).toBe(true)
+  })
+
+  it('should compare objects with shared property values', () => {
+    const object1 = {
+      a: [1, 2]
+    }
+
+    const object2 = {
+      a: [1, 2],
+      b: [1, 2]
+    }
+
+    object1.b = object1.a
+
+    expect(equals(object1, object2)).toBe(true)
+  })
+
+  it('should avoid common type coercions', () => {
+    expect(equals(true, Object(false))).toBe(false)
+    expect(equals(Object(false), Object(0))).toBe(false)
+    expect(equals(false, Object(''))).toBe(false)
+    expect(equals(Object(36), Object('36'))).toBe(false)
+    expect(equals(0, '')).toBe(false)
+    expect(equals(1, true)).toBe(false)
+    expect(equals(1337756400000, new Date(2012, 4, 23))).toBe(false)
+    expect(equals('36', 36)).toBe(false)
+    expect(equals(36, '36')).toBe(false)
+  })
+
+  it('should compare functions', () => {
+    function a() {
+      return 1 + 2
+    }
+    function b() {
+      return 1 + 2
+    }
+
+    expect(equals(a, a)).toBe(true)
+    expect(equals(a, b)).toBe(false)
+  })
+})

package/src/object/groupBy.js

@@ -0,0 +1,15 @@
+import { isArray } from '../base/index.js'
+import { asCallback } from './asCallback.js'
+
+export function groupBy(collection, callback) {
+  const array = isArray(collection)
+    ? collection
+    : Object.values(collection)
+  callback = asCallback(callback)
+  return array.reduce((groups, item) => {
+    const key = callback(item)
+    const group = groups[key] || (groups[key] = [])
+    group.push(item)
+    return groups
+  }, {})
+}

package/src/object/groupBy.test.js

@@ -0,0 +1,70 @@
+import { groupBy } from './groupBy.js'
+
+describe('groupBy()', () => {
+  const array = [6.1, 4.2, 6.3]
+
+  it('should group entries by the result of `callback`', () => {
+    const actual1 = groupBy(array, Math.floor)
+    expect(actual1).toStrictEqual({ 4: [4.2], 6: [6.1, 6.3] })
+
+    const actual2 = groupBy(['one', 'two', 'three'], value => value.length)
+    expect(actual2).toStrictEqual({ 3: ['one', 'two'], 5: ['three'] })
+  })
+
+  it('should group by numbers and strings', () => {
+    const array = [
+      [1, 'a'],
+      [2, 'a'],
+      [2, 'b']
+    ]
+    expect(groupBy(array, value => value[0])).toStrictEqual({
+      1: [[1, 'a']],
+      2: [[2, 'a'], [2, 'b']]
+    })
+    expect(groupBy(array, value => value[1])).toStrictEqual({
+      a: [[1, 'a'], [2, 'a']],
+      b: [[2, 'b']]
+    })
+  })
+
+  it('should work with an object for `collection`', () => {
+    const actual = groupBy({ a: 6.1, b: 4.2, c: 6.3 }, Math.floor)
+    expect(actual).toStrictEqual({ 4: [4.2], 6: [6.1, 6.3] })
+  })
+
+  it('should support string property accessor', () => {
+    const array = [
+      { category: 'fruit', name: 'apple' },
+      { category: 'vegetable', name: 'carrot' },
+      { category: 'fruit', name: 'banana' }
+    ]
+    const actual = groupBy(array, 'category')
+    expect(actual).toStrictEqual({
+      fruit: [
+        { category: 'fruit', name: 'apple' },
+        { category: 'fruit', name: 'banana' }
+      ],
+      vegetable: [
+        { category: 'vegetable', name: 'carrot' }
+      ]
+    })
+  })
+
+  it('should group by string property with numbers', () => {
+    const array = [
+      { id: 1, value: 'a' },
+      { id: 2, value: 'b' },
+      { id: 1, value: 'c' }
+    ]
+    const actual = groupBy(array, 'id')
+    expect(actual).toStrictEqual({
+      1: [
+        { id: 1, value: 'a' },
+        { id: 1, value: 'c' }
+      ],
+      2: [
+        { id: 2, value: 'b' }
+      ]
+    })
+  })
+})

package/src/object/index.js

@@ -0,0 +1,8 @@
+export * from './clone.js'
+export * from './equals.js'
+export * from './groupBy.js'
+export * from './mapKeys.js'
+export * from './mapValues.js'
+export * from './mergeDeeply.js'
+export * from './pick.js'
+export * from './pickBy.js'

package/src/object/mapKeys.js

@@ -0,0 +1,7 @@
+export function mapKeys(object, callback) {
+  return Object.keys(object).reduce((mapped, key) => {
+    const value = object[key]
+    mapped[callback(key, value, object)] = value
+    return mapped
+  }, {})
+}

package/src/object/mapKeys.test.js

@@ -0,0 +1,16 @@
+import { mapKeys } from './mapKeys.js'
+
+describe('mapKeys()', () => {
+  const array = [1, 2]
+  const object = { a: 1, b: 2 }
+
+  it('should map keys in `object` to a new object', () => {
+    const actual = mapKeys(object, (key, value) => String(value))
+    expect(actual).toStrictEqual({ 1: 1, 2: 2 })
+  })
+
+  it('should treat arrays like objects', () => {
+    const actual = mapKeys(array, (key, value) => String(value))
+    expect(actual).toStrictEqual({ 1: 1, 2: 2 })
+  })
+})

package/src/object/mapValues.js

@@ -0,0 +1,9 @@
+import { asCallback } from './asCallback.js'
+
+export function mapValues(object, callback) {
+  callback = asCallback(callback)
+  return Object.keys(object).reduce((mapped, key) => {
+    mapped[key] = callback(object[key], key, object)
+    return mapped
+  }, {})
+}

package/src/object/mapValues.test.js

@@ -0,0 +1,38 @@
+import { mapValues } from './mapValues.js'
+
+describe('mapValues()', () => {
+  const array = [1, 2]
+  const object = { a: 1, b: 2 }
+
+  it('should map values in `object` to a new object', () => {
+    const actual = mapValues(object, String)
+    expect(actual).toStrictEqual({ a: '1', b: '2' })
+  })
+
+  it('should treat arrays like objects', () => {
+    const actual = mapValues(array, String)
+    expect(actual).toStrictEqual({ 0: '1', 1: '2' })
+  })
+
+  it('should support string property accessor', () => {
+    const users = {
+      user1: { id: 1, name: 'Alice', email: 'alice@example.com' },
+      user2: { id: 2, name: 'Bob', email: 'bob@example.com' }
+    }
+    const actual = mapValues(users, 'email')
+    expect(actual).toStrictEqual({
+      user1: 'alice@example.com',
+      user2: 'bob@example.com'
+    })
+  })
+
+  it('should extract nested properties with string accessor', () => {
+    const data = {
+      a: { value: 10 },
+      b: { value: 20 },
+      c: { value: 30 }
+    }
+    const actual = mapValues(data, 'value')
+    expect(actual).toStrictEqual({ a: 10, b: 20, c: 30 })
+  })
+})

package/src/object/mergeDeeply.js

@@ -0,0 +1,47 @@
+import { isArray, isPlainObject } from '../base/index.js'
+import { clone } from './clone.js'
+
+export function mergeDeeply(target, ...sources) {
+  for (const source of sources) {
+    target = mergeValues(target, source, true, true)
+  }
+  return target
+}
+
+export function assignDeeply(target, ...sources) {
+  for (const source of sources) {
+    target = mergeValues(target, source, true, false)
+  }
+  return target
+}
+
+function mergeValues(target, source, root, concat) {
+  if (target && source && target !== source) {
+    if (isArray(target) && isArray(source)) {
+      return mergeIteratively(target, source, root, concat, true)
+    } else if (isPlainObject(target) && isPlainObject(source)) {
+      return mergeIteratively(target, source, root, concat, false)
+    }
+  }
+  return root // Don't override values with nullish at root level
+    ? source ?? target
+    : source
+}
+
+function mergeIteratively(target, source, root, concat, toArray) {
+  const result = root
+    ? target
+    : clone(target, { shallow: true })
+  for (const key of Object.keys(source)) {
+    const to = target[key]
+    const from = source[key]
+    const value = mergeValues(to, from, false, concat)
+    if (value === from && toArray && concat) {
+      // Append non-mergeable values to the end of results array.
+      result.push(value)
+    } else {
+      result[key] = value
+    }
+  }
+  return result
+}

package/src/object/mergeDeeply.test.js

@@ -0,0 +1,152 @@
+import { mergeDeeply, assignDeeply } from './mergeDeeply.js'
+
+describe('mergeDeeply()', () => {
+  it('should merge nested objects', () => {
+    const source1 = { a: { b: [] } }
+    const source2 = { a: { c: [] } }
+    const expected = { a: { b: [], c: [] } }
+    expect(mergeDeeply({}, source1, source2)).toStrictEqual(expected)
+    expect(mergeDeeply({}, source2, source1)).toStrictEqual(expected)
+  })
+
+  it('should override keys in target with different types', () => {
+    const source1 = { a: { b: 1 } }
+    const source2 = { a: { b: [] } }
+    expect(mergeDeeply({}, source1, source2)).toStrictEqual(source2)
+    expect(mergeDeeply({}, source2, source1)).toStrictEqual(source1)
+  })
+
+  it('should merge objects at the same indices inside arrays', () => {
+    const source1 = [{ a: 1 }, { b: 2 }]
+    const source2 = [{ c: 3 }, { d: 4 }]
+    const expected = [{ a: 1, c: 3 }, { b: 2, d: 4 }]
+    expect(mergeDeeply([], source1, source2)).toStrictEqual(expected)
+  })
+
+  it('should merge `source` into `object`', () => {
+    const names = {
+      characters: [
+        { name: 'barney' },
+        { name: 'fred' }
+      ]
+    }
+
+    const ages = {
+      characters: [
+        { age: 36 },
+        { age: 40 }
+      ]
+    }
+
+    const heights = {
+      characters: [
+        { height: '5\'4"' },
+        { height: '5\'5"' }
+      ]
+    }
+
+    const expected = {
+      characters: [
+        { name: 'barney', age: 36, height: '5\'4"' },
+        { name: 'fred', age: 40, height: '5\'5"' }
+      ]
+    }
+
+    expect(mergeDeeply(names, ages, heights)).toEqual(expected)
+  })
+
+  it('should handle plain values', () => {
+    expect(mergeDeeply(true, false)).toEqual(false)
+    expect(mergeDeeply(10, 0)).toEqual(0)
+    expect(mergeDeeply(0, 10)).toEqual(10)
+    expect(mergeDeeply('foo', 'bar')).toEqual('bar')
+  })
+
+  it('should not override values with nullish values at root level', () => {
+    expect(mergeDeeply({}, null)).toEqual({})
+    expect(mergeDeeply([], null)).toEqual([])
+    expect(mergeDeeply(10, null)).toEqual(10)
+    expect(mergeDeeply(false, null)).toEqual(false)
+  })
+
+  it('should work with multiple arguments', () => {
+    const expected = { a: 4 }
+    const actual = mergeDeeply({ a: 1 }, { a: 2 }, { a: 3 }, expected)
+
+    expect(actual).toStrictEqual(expected)
+  })
+
+  it('should not augment source objects', () => {
+    const source1 = { a: [{ a: 1 }] }
+    const source2 = { a: [{ b: 2 }] }
+    const actual1 = mergeDeeply({}, source1, source2)
+
+    expect(source1.a).toStrictEqual([{ a: 1 }])
+    expect(source2.a).toStrictEqual([{ b: 2 }])
+    expect(actual1.a).toStrictEqual([{ a: 1, b: 2 }])
+
+    const source3 = { a: [[1, 2, 3]] }
+    const source4 = { a: [[4, 5]] }
+    const actual2 = mergeDeeply({}, source3, source4)
+
+    expect(source3.a).toStrictEqual([[1, 2, 3]])
+    expect(source4.a).toStrictEqual([[4, 5]])
+    expect(actual2.a).toStrictEqual([[1, 2, 3, 4, 5]])
+  })
+
+  it('should overwrite existing values with `undefined` in objects', () => {
+    const result = mergeDeeply({ a: 1 }, { a: undefined, b: undefined })
+    expect(result).toStrictEqual({ a: undefined, b: undefined })
+  })
+
+  it('should not overwrite existing values with `undefined` in arrays', () => {
+    const result1 = mergeDeeply([4, 5, 6], [1, undefined, 3])
+    expect(result1).toStrictEqual([4, 5, 6, 1, undefined, 3])
+
+    // eslint-disable-next-line no-sparse-arrays
+    const result2 = mergeDeeply([4, 5, 6], [1, , 3])
+    expect(result2).toStrictEqual([4, 5, 6, 1, 3])
+  })
+
+  it('should merge regexps', () => {
+    const source1 = { a: /1/ }
+    const source2 = { a: /2/ }
+    const expected = { a: /2/ }
+    expect(mergeDeeply({}, source1, source2)).toStrictEqual(expected)
+  })
+
+  it('should merge dates', () => {
+    const source1 = { a: new Date(2012, 5, 9) }
+    const source2 = { a: new Date(2021, 5, 9) }
+    const expected = { a: new Date(2021, 5, 9) }
+    expect(mergeDeeply({}, source1, source2)).toStrictEqual(expected)
+  })
+
+  it('should be fine with nested promises', async () => {
+    const promise1 = (async () => 1)()
+    const promise2 = (async () => 2)()
+    const source1 = { nested: { promise1 } }
+    const source2 = { nested: { promise2 } }
+    const expected = { nested: { promise1, promise2 } }
+    const result = mergeDeeply({}, source1, source2)
+    expect(result).toStrictEqual(expected)
+    expect(await result.nested.promise1).toStrictEqual(1)
+    expect(await result.nested.promise2).toStrictEqual(2)
+  })
+})
+
+describe('assignDeeply()', () => {
+  it('should not concat-merge arrays', () => {
+    const result = assignDeeply({}, { a: [[1, 2, 3]] }, { a: [[4, 5]] })
+    expect(result).toStrictEqual({ a: [[4, 5, 3]] })
+  })
+
+  it('should overwrite existing values with `undefined` in arrays', () => {
+    const result1 = assignDeeply([4, 5, 6], [1, undefined, 3])
+    expect(result1).toStrictEqual([1, undefined, 3])
+
+    // eslint-disable-next-line no-sparse-arrays
+    const result2 = assignDeeply([4, 5, 6], [1, , 3])
+    expect(result2).toStrictEqual([1, 5, 3])
+  })
+})

package/src/object/pick.js

@@ -0,0 +1,11 @@
+export function pick(...args) {
+  // Optimize for the most common case of two arguments:
+  if (args.length === 2) {
+    return args[0] !== undefined ? args[0] : args[1]
+  }
+  for (const arg of args) {
+    if (arg !== undefined) {
+      return arg
+    }
+  }
+}

package/src/object/pick.test.js

@@ -0,0 +1,23 @@
+import { pick } from './pick.js'
+
+// Partially based on:
+// https://github.com/lodash/lodash/blob/4.17.11/test/test.js
+
+describe('pick()', () => {
+  it(`should return the first value that isn't undefined`, () => {
+    expect(pick(10)).toBe(10)
+    expect(pick(10, undefined)).toBe(10)
+    expect(pick(undefined, 10)).toBe(10)
+    expect(pick(undefined, undefined, 10)).toBe(10)
+  })
+
+  it('should consider null as defined', () => {
+    expect(pick(null)).toBeNull()
+    expect(pick(undefined, null)).toBeNull()
+  })
+
+  it('should return undefined if nothing is defined', () => {
+    expect(pick()).toBeUndefined()
+    expect(pick(undefined)).toBeUndefined()
+  })
+})

package/src/object/pickBy.js

@@ -0,0 +1,11 @@
+import { asCallback } from './asCallback.js'
+
+export function pickBy(object, callback) {
+  callback = asCallback(callback)
+  return Object.entries(object).reduce((result, [key, value]) => {
+    if (callback(value, key, object)) {
+      result[key] = value
+    }
+    return result
+  }, {})
+}