@ditojs/utils 2.5.0 → 2.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ditojs/utils",
-  "version": "2.5.0",
+  "version": "2.7.0",
   "type": "module",
   "description": "Dito.js Utility Functions – Dito.js is a declarative and modern web framework, based on Objection.js, Koa.js and Vue.js",
   "repository": "https://github.com/ditojs/dito/tree/master/packages/utils",
@@ -32,7 +32,7 @@
     "typescript": "^5.0.4"
   },
   "types": "types",
-  "gitHead": "1339a92f8adbfabee89d516ccfca84e13b48833b",
+  "gitHead": "874c68d5807ba97b67867f6b8d13f8fcb4990533",
   "scripts": {
     "types": "tsc --noEmit types/index.d.ts"
   },

package/src/__snapshots__/index.test.js.snap

@@ -5,6 +5,7 @@ exports[`index > exports all symbols 1`] = `
   "asArray": [Function],
   "asFunction": [Function],
   "asObject": [Function],
+  "assignDeeply": [Function],
   "camelize": [Function],
   "capitalize": [Function],
   "clone": [Function],
@@ -27,6 +28,7 @@ exports[`index > exports all symbols 1`] = `
     },
   },
   "deindent": [Function],
+  "deprecate": [Function],
   "equals": [Function],
   "escapeHtml": [Function],
   "escapeRegexp": [Function],
@@ -67,6 +69,7 @@ exports[`index > exports all symbols 1`] = `
   "mapSequentially": [Function],
   "mapValues": [Function],
   "merge": [Function],
+  "mergeDeeply": [Function],
   "mixin": [Function],
   "normalizeDataPath": [Function],
   "parseDataPath": [Function],

package/src/function/deprecate.js

@@ -0,0 +1,9 @@
+const loggedDeprecations = new Set()
+
+export function deprecate(message) {
+  // Only log deprecation messages once.
+  if (!loggedDeprecations.has(message)) {
+    loggedDeprecations.add(message)
+    console.warn(message)
+  }
+}

package/src/function/index.js

@@ -1,3 +1,4 @@
+export * from './deprecate.js'
 export * from './toAsync.js'
 export * from './toCallback.js'
 export * from './toPromiseCallback.js'

package/src/object/index.js

@@ -3,6 +3,6 @@ export * from './equals.js'
 export * from './groupBy.js'
 export * from './mapKeys.js'
 export * from './mapValues.js'
-export * from './merge.js'
+export * from './mergeDeeply.js'
 export * from './pick.js'
 export * from './pickBy.js'

package/src/object/mergeDeeply.js

@@ -0,0 +1,51 @@
+import { isArray, isPlainObject } from '../base/index.js'
+import { deprecate } from '../function/deprecate.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 merge(...args) {
+  deprecate('merge() is deprecated, use mergeDeeply() instead.')
+  return mergeDeeply(...args)
+}
+
+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 ? 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/{merge.test.js → mergeDeeply.test.js}

@@ -1,26 +1,26 @@
-import { merge } from './merge.js'
+import { mergeDeeply, assignDeeply } from './mergeDeeply.js'
 
-describe('merge()', () => {
+describe('mergeDeeply()', () => {
   it('should merge nested objects', () => {
     const source1 = { a: { b: [] } }
     const source2 = { a: { c: [] } }
     const expected = { a: { b: [], c: [] } }
-    expect(merge({}, source1, source2)).toStrictEqual(expected)
-    expect(merge({}, source2, source1)).toStrictEqual(expected)
+    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(merge({}, source1, source2)).toStrictEqual(source2)
-    expect(merge({}, source2, source1)).toStrictEqual(source1)
+    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(merge([], source1, source2)).toStrictEqual(expected)
+    expect(mergeDeeply([], source1, source2)).toStrictEqual(expected)
   })
 
   it('should merge `source` into `object`', () => {
@@ -52,12 +52,26 @@ describe('merge()', () => {
       ]
     }
 
-    expect(merge(names, ages, heights)).toEqual(expected)
+    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 = merge({ a: 1 }, { a: 2 }, { a: 3 }, expected)
+    const actual = mergeDeeply({ a: 1 }, { a: 2 }, { a: 3 }, expected)
 
     expect(actual).toStrictEqual(expected)
   })
@@ -65,7 +79,7 @@ describe('merge()', () => {
   it('should not augment source objects', () => {
     const source1 = { a: [{ a: 1 }] }
     const source2 = { a: [{ b: 2 }] }
-    const actual1 = merge({}, source1, source2)
+    const actual1 = mergeDeeply({}, source1, source2)
 
     expect(source1.a).toStrictEqual([{ a: 1 }])
     expect(source2.a).toStrictEqual([{ b: 2 }])
@@ -73,7 +87,7 @@ describe('merge()', () => {
 
     const source3 = { a: [[1, 2, 3]] }
     const source4 = { a: [[4, 5]] }
-    const actual2 = merge({}, source3, source4)
+    const actual2 = mergeDeeply({}, source3, source4)
 
     expect(source3.a).toStrictEqual([[1, 2, 3]])
     expect(source4.a).toStrictEqual([[4, 5]])
@@ -81,33 +95,31 @@ describe('merge()', () => {
   })
 
   it('should overwrite existing values with `undefined` in objects', () => {
-    const actual = merge({ a: 1 }, { a: undefined, b: undefined })
-    expect(actual).toStrictEqual({ a: undefined, b: undefined })
+    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 array1 = [1, undefined, 3]
-    const actual1 = merge([4, 5, 6], array1)
-    expect(actual1).toStrictEqual([4, 5, 6, 1, undefined, 3])
+    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 array2 = [1, , 3]
-    const actual2 = merge([4, 5, 6], array2)
-    expect(actual2).toStrictEqual([4, 5, 6, 1, 3])
+    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(merge({}, source1, source2)).toStrictEqual(expected)
+    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(merge({}, source1, source2)).toStrictEqual(expected)
+    expect(mergeDeeply({}, source1, source2)).toStrictEqual(expected)
   })
 
   it('should be fine with nested promises', async () => {
@@ -116,9 +128,25 @@ describe('merge()', () => {
     const source1 = { nested: { promise1 } }
     const source2 = { nested: { promise2 } }
     const expected = { nested: { promise1, promise2 } }
-    const result = merge({}, source1, source2)
+    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/types/index.d.ts

@@ -148,27 +148,49 @@ export function groupBy<T, K extends string | number | symbol>(
   callback: (item: T) => K
 ): Record<K, T[]>
 
-// TODO: document merge
-export function merge<ArgA, ArgB>(a: ArgA, b: ArgB): ArgA & ArgB
-export function merge<ArgA, ArgB, ArgC>(
+// TODO: document mergeDeeply
+export function mergeDeeply<ArgA, ArgB>(a: ArgA, b: ArgB): ArgA & ArgB
+export function mergeDeeply<ArgA, ArgB, ArgC>(
   a: ArgA,
   b: ArgB,
   c: ArgC
 ): ArgA & ArgB & ArgC
-export function merge<ArgA, ArgB, ArgC, ArgD>(
+export function mergeDeeply<ArgA, ArgB, ArgC, ArgD>(
   a: ArgA,
   b: ArgB,
   c: ArgC,
   d: ArgD
 ): ArgA & ArgB & ArgC & ArgD
-export function merge<ArgA, ArgB, ArgC, ArgD, ArgE>(
+export function mergeDeeply<ArgA, ArgB, ArgC, ArgD, ArgE>(
   a: ArgA,
   b: ArgB,
   c: ArgC,
   d: ArgD,
   e: ArgE
 ): ArgA & ArgB & ArgC & ArgD & ArgE
-export function merge(...args: any[]): any
+export function mergeDeeply(...args: any[]): any
+
+// TODO: document assignDeeply
+export function assignDeeply<ArgA, ArgB>(a: ArgA, b: ArgB): ArgA & ArgB
+export function assignDeeply<ArgA, ArgB, ArgC>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC
+): ArgA & ArgB & ArgC
+export function assignDeeply<ArgA, ArgB, ArgC, ArgD>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD
+): ArgA & ArgB & ArgC & ArgD
+export function assignDeeply<ArgA, ArgB, ArgC, ArgD, ArgE>(
+  a: ArgA,
+  b: ArgB,
+  c: ArgC,
+  d: ArgD,
+  e: ArgE
+): ArgA & ArgB & ArgC & ArgD & ArgE
+export function assignDeeply(...args: any[]): any
 
 /**
  * Returns the first argument which is not undefined.

package/src/object/merge.js

@@ -1,41 +0,0 @@
-import { isArray, isPlainObject } from '../base/index.js'
-import { clone } from './clone.js'
-
-export function merge(target, ...sources) {
-  const mergeIteratively = (target, source, cloneTarget, concat) => {
-    const result = cloneTarget
-      ? clone(target, { shallow: true })
-      : target
-    for (const key of Object.keys(source)) {
-      const to = target[key]
-      const from = source[key]
-      if (
-        !concat ||
-        isArray(to) && isArray(from) ||
-        isPlainObject(to) && isPlainObject(from)
-      ) {
-        result[key] = mergeValues(to, from, true)
-      } else {
-        // Append non-mergeable values to the end of results.
-        result.push(from)
-      }
-    }
-    return result
-  }
-
-  const mergeValues = (target, source, cloneTarget) => {
-    if (target && source && target !== source) {
-      if (isArray(target) && isArray(source)) {
-        return mergeIteratively(target, source, cloneTarget, true)
-      } else if (isPlainObject(target) && isPlainObject(source)) {
-        return mergeIteratively(target, source, cloneTarget, false)
-      }
-    }
-    return source
-  }
-
-  for (const source of sources) {
-    mergeValues(target, source, false)
-  }
-  return target
-}