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

package/src/dataPath/setValueAtDataPath.test.js

@@ -0,0 +1,34 @@
+import { setValueAtDataPath } from './setValueAtDataPath.js'
+
+describe('setValueAtDataPath()', () => {
+  const data = {
+    object: {
+      array: [
+        {}
+      ],
+      number: 10
+    }
+  }
+
+  const add = { prop: 'new' }
+
+  it('should add data at a path to a given object', () => {
+    expect(() => setValueAtDataPath(data, 'object.array[0].added', add))
+      .not.toThrow()
+    expect(data.object.array[0].added).toStrictEqual(add)
+  })
+
+  it('should add data at a path to a given array', () => {
+    expect(() => setValueAtDataPath(data, 'object.array[1]', add)).not.toThrow()
+    expect(data.object.array[1]).toStrictEqual(add)
+  })
+
+  it('should throw an error with faulty paths', () => {
+    expect(() => setValueAtDataPath(data, 'object/unknown/prop', add)).toThrow()
+  })
+
+  it('should throw an error with invalid target', () => {
+    expect(() => setValueAtDataPath(data, 'object/number/invalid', add))
+      .toThrow('Invalid path: object/number/invalid')
+  })
+})

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

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

package/src/function/toAsync.js

@@ -0,0 +1,9 @@
+import { toPromiseCallback } from './toPromiseCallback.js'
+
+export function toAsync(callbackFunction) {
+  return (...args) => {
+    return new Promise((resolve, reject) => {
+      callbackFunction(...args, toPromiseCallback(resolve, reject))
+    })
+  }
+}

package/src/function/toAsync.test.js

@@ -0,0 +1,31 @@
+import { toAsync } from './toAsync.js'
+
+describe('toAsync()', () => {
+  it('should convert callback functions to async', async () => {
+    expect.assertions(1)
+    const asyncFunc = toAsync(function (toResolve, callback) {
+      process.nextTick(() => {
+        callback(null, toResolve)
+      })
+    })
+    const expected = 10
+    const actual = await asyncFunc(expected)
+    expect(actual).toBe(expected)
+  })
+
+  it('should convert callback errors to exceptions', async () => {
+    expect.assertions(1)
+    const error = new Error('This error is intentional')
+    const throwError = toAsync(function (toReject, callback) {
+      process.nextTick(() => {
+        callback(toReject)
+      })
+    })
+
+    try {
+      await throwError(error)
+    } catch (err) {
+      expect(err).toBe(error)
+    }
+  })
+})

package/src/function/toCallback.js

@@ -0,0 +1,11 @@
+export function toCallback(asyncFunction) {
+  return async (...args) => {
+    // The last argument is the callback function
+    const done = args.pop()
+    try {
+      done(null, await asyncFunction(...args))
+    } catch (err) {
+      done(err)
+    }
+  }
+}

package/src/function/toCallback.test.js

@@ -0,0 +1,29 @@
+import { toCallback } from './toCallback.js'
+
+describe('toCallback()', () => {
+  it('should convert async functions to callbacks', async () => {
+    expect.assertions(2)
+    const callback = toCallback(async result => {
+      await Promise.resolve()
+      return result
+    })
+    const expected = 10
+    callback(expected, (err, actual) => {
+      expect(err).toBeNull()
+      expect(actual).toBe(expected)
+    })
+  })
+
+  it('should convert async exceptions to callback errors', async () => {
+    expect.assertions(2)
+    const error = new Error('This error is intentional')
+    const callback = toCallback(async error => {
+      await Promise.resolve()
+      throw error
+    })
+    callback(error, (err, actual) => {
+      expect(err).toBe(error)
+      expect(actual).toBe(undefined)
+    })
+  })
+})

package/src/function/toPromiseCallback.js

@@ -0,0 +1,9 @@
+export function toPromiseCallback(resolve, reject) {
+  return (err, res) => {
+    if (err) {
+      reject(err)
+    } else {
+      resolve(res)
+    }
+  }
+}

package/src/function/toPromiseCallback.test.js

@@ -0,0 +1,24 @@
+import { toPromiseCallback } from './toPromiseCallback.js'
+import { vi } from 'vitest'
+
+describe('toPromiseCallback()', () => {
+  it('should call reject() when called with an error', () => {
+    const error = new Error('My Error')
+    const resolve = vi.fn()
+    const reject = vi.fn()
+    const callback = toPromiseCallback(resolve, reject)
+    callback(error)
+    expect(resolve).not.toBeCalled()
+    expect(reject).toBeCalledWith(error)
+  })
+
+  it('should call resolve() when called with a result', () => {
+    const result = 42
+    const resolve = vi.fn()
+    const reject = vi.fn()
+    const callback = toPromiseCallback(resolve, reject)
+    callback(null, result)
+    expect(reject).not.toBeCalled()
+    expect(resolve).toBeCalledWith(result)
+  })
+})

package/src/html/escapeHtml.js

@@ -0,0 +1,11 @@
+export function escapeHtml(html) {
+  return html != null
+    ? html
+        .toString()
+        .replace(
+          /["&<>]/g,
+          chr =>
+            ({ '"': '&quot;', '&': '&amp;', '<': '&lt;', '>': '&gt;' })[chr]
+        )
+    : ''
+}

package/src/html/escapeHtml.test.js

@@ -0,0 +1,19 @@
+import { escapeHtml } from './escapeHtml.js'
+
+describe('escapeHtml()', () => {
+  it('should escape quotes, ampersands, and smaller/greater than signs', () => {
+    expect(escapeHtml('<div id="me, myself & i"/>'))
+      .toBe('&lt;div id=&quot;me, myself &amp; i&quot;/&gt;')
+  })
+
+  it('should return an empty string if nothing can be processed', () => {
+    expect(escapeHtml()).toBe('')
+    expect(escapeHtml(null)).toBe('')
+    expect(escapeHtml('')).toBe('')
+  })
+
+  it('should handle falsy values correctly', () => {
+    expect(escapeHtml(0)).toBe('0')
+    expect(escapeHtml(false)).toBe('false')
+  })
+})

package/src/html/index.js

@@ -0,0 +1,2 @@
+export * from './escapeHtml.js'
+export * from './stripHtml.js'

package/src/html/stripHtml.js

@@ -0,0 +1,23 @@
+import { deprecate } from '../function/deprecate.js'
+
+export function stripHtml(html) {
+  return html != null
+    ? html
+        .toString()
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/p>/gi, '\n')
+        .replace(/<[^>]+>/g, '')
+        .trim()
+    : ''
+}
+
+/**
+ * @deprecated Use stripHtml() instead
+ */
+export function stripTags(html) {
+  deprecate(
+    'The `stripTags` function is deprecated in favour of `stripHtml`. ' +
+    'Update your code to use `stripHtml` instead.'
+  )
+  return stripHtml(html)
+}

package/src/html/stripHtml.test.js

@@ -0,0 +1,37 @@
+import { stripHtml } from './stripHtml.js'
+
+describe('stripHtml()', () => {
+  it('should remove html tags from strings', () => {
+    expect(stripHtml('<p><b>this</b> is a marked-up string</p>'))
+      .toBe('this is a marked-up string')
+  })
+
+  it('should return an empty string if nothing can be processed', () => {
+    expect(stripHtml()).toBe('')
+    expect(stripHtml(null)).toBe('')
+    expect(stripHtml('')).toBe('')
+  })
+
+  it('should handle falsy values correctly', () => {
+    expect(stripHtml(0)).toBe('0')
+    expect(stripHtml(false)).toBe('false')
+  })
+
+  it('should convert <br> tags to line-breaks', () => {
+    expect(stripHtml('hello<br>world')).toBe('hello\nworld')
+    expect(stripHtml('hello<br/>world')).toBe('hello\nworld')
+    expect(stripHtml('hello<br />world')).toBe('hello\nworld')
+  })
+
+  it('should convert <p> tags to line-breaks', () => {
+    expect(stripHtml('<p>First paragraph</p><p>Second paragraph</p>'))
+      .toBe('First paragraph\nSecond paragraph')
+    expect(stripHtml('<p>Only paragraph</p>'))
+      .toBe('Only paragraph')
+  })
+
+  it('should trim leading and trailing whitespace', () => {
+    expect(stripHtml('  <p>text</p>  ')).toBe('text')
+    expect(stripHtml('<p>  text  </p>')).toBe('text')
+  })
+})

package/src/index.js

@@ -0,0 +1,10 @@
+export * from './base/index.js'
+export * from './class/index.js'
+export * from './array/index.js'
+export * from './object/index.js'
+export * from './string/index.js'
+export * from './timer/index.js'
+export * from './promise/index.js'
+export * from './function/index.js'
+export * from './dataPath/index.js'
+export * from './html/index.js'

package/src/index.test.js

@@ -0,0 +1,7 @@
+import * as index from './index.js'
+
+describe('index', () => {
+  it('exports all symbols', () => {
+    expect(index).toMatchSnapshot()
+  })
+})

package/src/object/asCallback.js

@@ -0,0 +1,9 @@
+import { isString } from '../base/index.js'
+
+export function asCallback(callback) {
+  if (isString(callback)) {
+    const key = callback
+    return value => value[key]
+  }
+  return callback
+}

package/src/object/clone.js

@@ -0,0 +1,75 @@
+import {
+  isArray,
+  isObject,
+  isDate,
+  isRegExp,
+  isFunction,
+  isPromise
+} from '../base/index.js'
+import { pick } from './pick.js'
+
+export function clone(value, options) {
+  const {
+    shallow = false,
+    enumerable = true,
+    descriptors = !enumerable,
+    transferables = null,
+    processValue = null
+  } = options ?? {}
+
+  const clones = new Map()
+
+  const storeClone = (value, copy) => {
+    clones.set(value, copy)
+    return copy
+  }
+
+  const handleValue = value =>
+    shallow || transferables?.includes(value)
+      ? value
+      : clones.has(value)
+        ? clones.get(value)
+        : cloneValue(value)
+
+  const cloneValue = value => {
+    let copy = value
+    if (isDate(value)) {
+      copy = storeClone(value, new value.constructor(+value))
+    } else if (isRegExp(value)) {
+      copy = storeClone(value, new value.constructor(value))
+    } else if (isArray(value)) {
+      copy = storeClone(value, new value.constructor(value.length))
+      for (let i = 0, l = value.length; i < l; i++) {
+        copy[i] = handleValue(value[i])
+      }
+    } else if (isObject(value)) {
+      // Rely on arg.clone() if it exists and assume it creates an actual clone.
+      if (isFunction(value.clone)) {
+        copy = storeClone(value, value.clone(options))
+      } else if (isPromise(value)) {
+        // https://stackoverflow.com/questions/37063293/can-i-clone-a-promise
+        copy = storeClone(value, value.then())
+      } else {
+        // Prevent calling the actual constructor since it is not guaranteed to
+        // work as intended here, and only clone non-inherited own properties.
+        copy = storeClone(value, Object.create(Object.getPrototypeOf(value)))
+        clones.set(value, copy)
+        const keys = enumerable ? Object.keys(value) : Reflect.ownKeys(value)
+        for (const key of keys) {
+          if (descriptors) {
+            const desc = Reflect.getOwnPropertyDescriptor(value, key)
+            if (desc.value != null) {
+              desc.value = handleValue(desc.value)
+            }
+            Reflect.defineProperty(copy, key, desc)
+          } else {
+            copy[key] = handleValue(value[key])
+          }
+        }
+      }
+    }
+    return pick(processValue?.(copy), copy)
+  }
+
+  return cloneValue(value)
+}

package/src/object/clone.test.js

@@ -0,0 +1,131 @@
+import { clone } from './clone.js'
+import { vi } from 'vitest'
+
+describe('clone()', () => {
+  it('should clone objects', () => {
+    const object = { a: 1, b: 2 }
+    const copy = clone(object)
+    expect(copy).toEqual(object)
+    expect(copy).not.toBe(object)
+  })
+
+  it('should clone arrays', () => {
+    const array = [1, 2, 3]
+    const copy = clone(array)
+    expect(copy).toStrictEqual(array)
+    expect(copy).not.toBe(array)
+  })
+
+  it('should clone dates', () => {
+    const date = new Date(2012, 5, 9)
+    const copy = clone(date)
+    expect(copy).toStrictEqual(date)
+    expect(copy).not.toBe(date)
+  })
+
+  it('should clone regular expressions', () => {
+    const regexp = /regexp/gi
+    const copy = clone(regexp)
+    expect(copy).toStrictEqual(regexp)
+    expect(copy).not.toBe(regexp)
+  })
+
+  it('should return functions unmodified', () => {
+    const func = () => {}
+    expect(clone(func)).toBe(func)
+  })
+
+  it('should clone nested objects and arrays', () => {
+    const object = { a: [1, 2, 3], b: { c: 4, d: 5 } }
+    const copy = clone(object)
+    expect(copy).toStrictEqual(object)
+    expect(copy).not.toBe(object)
+    expect(copy.a).not.toBe(object.a)
+    expect(copy.b).not.toBe(object.b)
+  })
+
+  it('should support shallow-cloning', () => {
+    const object = { a: [1, 2, 3] }
+    const copy = clone(object, { shallow: true })
+    expect(object.a).toBe(copy.a)
+  })
+
+  it('should use clone() methods if available', () => {
+    const object = {
+      a: 1,
+      clone: vi.fn(() => ({ b: 2 }))
+    }
+    const copy = clone(object)
+    expect(object.clone).toBeCalledTimes(1)
+    expect(copy).toStrictEqual({ b: 2 })
+  })
+
+  it('should preserve identity', async () => {
+    const object = { a: { b: 1 } }
+    object.c = object.a
+    const copy = clone(object)
+    expect(copy).toEqual(object)
+    expect(copy.c).toBe(copy.a)
+  })
+
+  it('should handle circular references', async () => {
+    const object = { a: { b: 1 } }
+    object.c = object
+    const copy = clone(object)
+    expect(copy).toEqual(object)
+    expect(copy.c).toBe(copy)
+  })
+
+  it('should handle non-enumerable properties', async () => {
+    const object = { a: 1 }
+    Object.defineProperty(object, 'b', { value: 2, enumerable: false })
+    const copy = clone(object, { enumerable: false })
+    expect(copy.a).toEqual(1)
+    expect(copy.b).toEqual(2)
+  })
+
+  it('should transform cloned values by `processValue`', () => {
+    const object = {
+      a: { b: 1, c: 2 },
+      d: { e: 3, f: 4 }
+    }
+    const copy = clone(object, {
+      processValue: value => {
+        if (typeof value === 'object') {
+          value.g = 5
+        }
+      }
+    })
+    const expected = {
+      a: { b: 1, c: 2, g: 5 },
+      d: { e: 3, f: 4, g: 5 },
+      g: 5
+    }
+    expect(copy).toStrictEqual(expected)
+  })
+
+  it('should call `processValue` after cloning all children', () => {
+    const array = [
+      { a: 1, b: 2 },
+      { a: 3, b: 4 }
+    ]
+    const copy = clone(array, {
+      processValue: value => {
+        if (typeof value === 'object') {
+          delete value.b
+        }
+      }
+    })
+    const expected = [
+      { a: 1 },
+      { a: 3 }
+    ]
+    expect(copy).toStrictEqual(expected)
+  })
+
+  it('should handle promises', async () => {
+    const promise = (async () => 1)()
+    const result = clone(promise)
+    expect(await result).toStrictEqual(1)
+  })
+})

package/src/object/equals.js

@@ -0,0 +1,36 @@
+import { is, isArray, isObject } from '../base/index.js'
+
+export function equals(arg1, arg2) {
+  if (arg1 === arg2) {
+    return true
+  }
+  if (arg1 != null && arg2 != null) {
+    arg1 = arg1.valueOf()
+    arg2 = arg2.valueOf()
+    if (is(arg1, arg2)) {
+      return true
+    }
+    if (isArray(arg1) && isArray(arg2)) {
+      let { length } = arg1
+      if (length === arg2.length) {
+        while (length--) {
+          if (!equals(arg1[length], arg2[length])) {
+            return false
+          }
+        }
+        return true
+      }
+    } else if (isObject(arg1) && isObject(arg2)) {
+      const keys = Object.keys(arg1)
+      if (keys.length === Object.keys(arg2).length) {
+        for (const key of keys) {
+          if (!(arg2.hasOwnProperty(key) && equals(arg1[key], arg2[key]))) {
+            return false
+          }
+        }
+        return true
+      }
+    }
+  }
+  return false
+}