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

package/src/string/labelize.js

@@ -0,0 +1,17 @@
+export function labelize(str) {
+  // Handle hyphenated, underscored and camel-cased property names and
+  // expand them to title cased labels.
+  return str
+    ? str.replace(
+        /[-_](?=\W)|([-_ ]|^)(\w)|([a-z])(?=[A-Z0-9])|(\d)([a-zA-Z])/g,
+        (all, hyphen, hyphenated, camel, decimal, decimalNext) =>
+          all === '-' || all === '_'
+            ? ' '
+            : hyphenated
+              ? `${hyphen ? ' ' : ''}${hyphenated.toUpperCase()}`
+              : camel
+                ? `${camel} `
+                : `${decimal} ${decimalNext.toUpperCase()}`
+      )
+    : ''
+}

package/src/string/labelize.test.js

@@ -0,0 +1,39 @@
+import { labelize } from './labelize.js'
+
+describe('labelize()', () => {
+  it('should labelize hyphenated text', () => {
+    expect(labelize('some-hyphenated-text')).toBe('Some Hyphenated Text')
+    expect(labelize('one-&-two', true)).toBe('One & Two')
+    expect(labelize('one-2-three', true)).toBe('One 2 Three')
+  })
+
+  it('should labelize underscored text', () => {
+    expect(labelize('some_underscored_text')).toBe('Some Underscored Text')
+  })
+
+  it('should labelize camel-cased text', () => {
+    expect(labelize('SomeCamelCasedText')).toBe('Some Camel Cased Text')
+  })
+
+  it('should labelize normal text', () => {
+    expect(labelize('some normal text')).toBe('Some Normal Text')
+  })
+
+  it('should split numbers and words', () => {
+    expect(labelize('one2')).toBe('One 2')
+  })
+
+  it('should split words and numbers both sides', () => {
+    expect(labelize('one2three')).toBe('One 2 Three')
+  })
+
+  it('should keep multiple numbers together', () => {
+    expect(labelize('one234five')).toBe('One 234 Five')
+  })
+
+  it('should return an empty string if nothing can be processed', () => {
+    expect(labelize()).toBe('')
+    expect(labelize(null)).toBe('')
+    expect(labelize('')).toBe('')
+  })
+})

package/src/timer/debounce.js

@@ -0,0 +1,34 @@
+import { isNumber } from '../base/index.js'
+
+export function debounce(func, options) {
+  const { delay, immediate } = isNumber(options) ? { delay: options } : options
+
+  let timer = null
+  let result
+
+  const debounced = function (...args) {
+    const callNow = immediate && !timer
+    clearTimeout(timer)
+    timer = setTimeout(async () => {
+      timer = null
+      if (!immediate) {
+        result = func.apply(this, args)
+      }
+    }, delay)
+    if (callNow) {
+      result = func.apply(this, args)
+    }
+    return result
+  }
+
+  debounced.cancel = function () {
+    const pending = timer !== null
+    if (pending) {
+      clearTimeout(timer)
+      timer = null
+    }
+    return pending
+  }
+
+  return debounced
+}

package/src/timer/debounce.test.js

@@ -0,0 +1,101 @@
+import { debounce } from './debounce.js'
+import { vi } from 'vitest'
+
+// Tell vitest to mock all timeout functions:
+vi.useFakeTimers()
+
+describe('debounce()', () => {
+  const fixture = Symbol('fixture')
+
+  it('should never execute if intervals are less than wait', () => {
+    const func = vi.fn()
+    const debounced = debounce(func, 1000)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      debounced()
+    }
+    expect(func).toBeCalledTimes(0)
+  })
+
+  it('should execute just once if an interval is big enough', () => {
+    const func = vi.fn()
+    const debounced = debounce(func, 1000)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      debounced()
+    }
+    vi.advanceTimersByTime(1000)
+    debounced()
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should pass through argument', async () => {
+    const func = vi.fn(value => value)
+    const debounced = debounce(func, 1000)
+    expect(debounced(fixture)).toBeUndefined()
+    vi.advanceTimersByTime(1000)
+    expect(debounced()).toBe(fixture)
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should pass through return value', () => {
+    const func = vi.fn().mockReturnValue(fixture)
+    const debounced = debounce(func, 1000)
+    expect(debounced()).toBeUndefined()
+    vi.advanceTimersByTime(1000)
+    expect(debounced()).toBe(fixture)
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should pass through `this`', () => {
+    const func = vi.fn().mockReturnThis()
+    const debounced = debounce(func, 0)
+    const obj = {}
+    expect(debounced.call(obj)).toBeUndefined()
+    vi.advanceTimersByTime(1000)
+    expect(debounced.call(obj)).toBe(obj)
+  })
+
+  it('should allow to cancel', () => {
+    const func = vi.fn()
+    const debounced = debounce(func, 1000)
+    debounced()
+    vi.advanceTimersByTime(500)
+    expect(debounced.cancel()).toBe(true)
+    expect(debounced.cancel()).toBe(false)
+    vi.advanceTimersByTime(500)
+    expect(func).toBeCalledTimes(0)
+    vi.advanceTimersByTime(1000)
+    expect(func).toBeCalledTimes(0)
+    debounced()
+    vi.advanceTimersByTime(1000)
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should execute once immediately if intervals are less than wait', () => {
+    const func = vi.fn()
+    const debounced = debounce(func, { delay: 1000, immediate: true })
+    debounced()
+    expect(func).toBeCalledTimes(1)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      debounced()
+    }
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it(`should execute once immediately and once at the end with long enough intervals`, () => {
+    const func = vi.fn()
+    const debounced = debounce(func, { delay: 1000, immediate: true })
+    debounced()
+    expect(func).toBeCalledTimes(1)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      debounced()
+    }
+    expect(func).toBeCalledTimes(1)
+    vi.advanceTimersByTime(1000)
+    debounced()
+    expect(func).toBeCalledTimes(2)
+  })
+})

package/src/timer/debounceAsync.js

@@ -0,0 +1,60 @@
+import { isNumber } from '../base/index.js'
+
+export function debounceAsync(func, options) {
+  const { delay, immediate } = isNumber(options) ? { delay: options } : options
+
+  let timer = null
+  let callbacks = []
+  let cancelled = false
+
+  const resolve = result => {
+    for (const { resolve } of callbacks) {
+      resolve(result)
+    }
+  }
+
+  const execute = async (that, args) => {
+    try {
+      resolve(await func.apply(that, args))
+    } catch (err) {
+      // Convention: reject the last waiting promise, while all the others are
+      // resolved with undefined.
+      const { reject } = callbacks.pop()
+      resolve(undefined)
+      reject(err)
+    }
+    callbacks = []
+  }
+
+  const debounced = function (...args) {
+    return new Promise((resolve, reject) => {
+      const callNow = immediate && !timer
+      clearTimeout(timer)
+      timer = setTimeout(() => {
+        timer = null
+        if (!immediate) {
+          execute(this, args)
+        }
+      }, delay)
+      callbacks.push({ resolve, reject })
+      if (cancelled) {
+        resolve(undefined)
+      } else if (callNow) {
+        execute(this, args)
+      }
+    })
+  }
+
+  debounced.cancel = function () {
+    const pending = timer !== null
+    if (pending) {
+      resolve(undefined)
+      clearTimeout(timer)
+      timer = null
+    }
+    cancelled = true
+    return pending
+  }
+
+  return debounced
+}

package/src/timer/debounceAsync.test.js

@@ -0,0 +1,143 @@
+import { debounceAsync } from './debounceAsync.js'
+import { vi } from 'vitest'
+
+// Tell vitest to mock all timeout functions:
+vi.useFakeTimers()
+
+describe('debounceAsync()', () => {
+  const fixture = Symbol('fixture')
+
+  it('should never execute if intervals are less than wait', () => {
+    const func = vi.fn()
+    const debounced = debounceAsync(func, 1000)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      debounced()
+    }
+    expect(func).toBeCalledTimes(0)
+  })
+
+  it('should execute just once if an interval is big enough', () => {
+    const func = vi.fn()
+    const debounced = debounceAsync(func, 1000)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      debounced()
+    }
+    vi.advanceTimersByTime(1000)
+    debounced()
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should pass through argument', async () => {
+    expect.assertions(2)
+    const func = vi.fn(async value => value)
+    const debounced = debounceAsync(func, 1000)
+    const promise = debounced(fixture)
+    vi.advanceTimersByTime(1000)
+    expect(await promise).toBe(fixture)
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should pass through return value', async () => {
+    expect.assertions(2)
+    const func = vi.fn().mockResolvedValueOnce(fixture)
+    const debounced = debounceAsync(func, 1000)
+    const promises = []
+    promises.push(debounced())
+    vi.advanceTimersByTime(1000)
+    promises.push(debounced())
+    expect(await Promise.all(promises)).toStrictEqual([fixture, fixture])
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should pass through `this`', async () => {
+    expect.assertions(2)
+    const func = vi.fn(async function () {
+      return this
+    })
+    const debounced = debounceAsync(func, 1000)
+    const obj = {}
+    const promises = []
+    promises.push(debounced.call(obj))
+    vi.advanceTimersByTime(1000)
+    promises.push(debounced.call(obj))
+    expect(await Promise.all(promises)).toStrictEqual([obj, obj])
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should allow to cancel', async () => {
+    expect.assertions(6)
+    const func = vi.fn()
+    const debounced = debounceAsync(func, 1000)
+    const promise = debounced()
+    vi.advanceTimersByTime(500)
+    expect(debounced.cancel()).toBe(true)
+    expect(debounced.cancel()).toBe(false)
+    vi.advanceTimersByTime(500)
+    expect(func).toBeCalledTimes(0)
+    expect(await promise).toBeUndefined()
+    vi.advanceTimersByTime(1000)
+    expect(func).toBeCalledTimes(0)
+    await debounced()
+    vi.advanceTimersByTime(1000)
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should execute once immediately if intervals are less than wait', async () => {
+    expect.assertions(2)
+    const func = vi.fn()
+    const debounced = debounceAsync(func, { delay: 1000, immediate: true })
+    const promises = []
+    promises.push(debounced())
+    expect(func).toBeCalledTimes(1)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      promises.push(debounced())
+    }
+    await Promise.all(promises)
+    expect(func).toBeCalledTimes(1)
+  })
+
+  it('should execute twice immediately with long enough intervals', async () => {
+    expect.assertions(3)
+    const func = vi.fn()
+    const debounced = debounceAsync(func, { delay: 1000, immediate: true })
+    const promises = []
+    promises.push(debounced())
+    expect(func).toBeCalledTimes(1)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      promises.push(debounced())
+    }
+    expect(func).toBeCalledTimes(1)
+    vi.advanceTimersByTime(1000)
+    promises.push(debounced())
+    await Promise.all(promises)
+    expect(func).toBeCalledTimes(2)
+  })
+
+  it('should only reject the last waiting promise', async () => {
+    expect.assertions(5)
+    let count = 0
+    const func = vi.fn(() => {
+      if (++count > 1) {
+        throw new Error('boom')
+      }
+    })
+    const debounced = debounceAsync(func, { delay: 1000, immediate: true })
+    const promises = []
+    promises.push(debounced())
+    expect(func).toBeCalledTimes(1)
+    for (let i = 0; i < 10; i++) {
+      vi.advanceTimersByTime(500)
+      promises.push(debounced())
+    }
+    expect(func).toBeCalledTimes(1)
+    vi.advanceTimersByTime(1000)
+    await expect(debounced()).rejects.toThrow('boom')
+    const results = await Promise.all(promises)
+    expect(results).toStrictEqual(new Array(11).fill(undefined))
+    expect(func).toBeCalledTimes(2)
+  })
+})

package/src/timer/index.js

@@ -0,0 +1,2 @@
+export * from './debounce.js'
+export * from './debounceAsync.js'