Add iterateUntilResult function

[aleclarson]

The iterateUntilResult function provides a flexible way to search through an array until finding a valid result. It processes items sequentially and supports both synchronous and asynchronous operations through Promise handling. This utility is particularly useful when you need to try multiple items in sequence until finding one that meets your criteria, gracefully handling both immediate returns and promise-based operations in a single interface.

Proposed implementation

import { isPromise } from 'radashi'

function iterateUntilResult<TItem, TResult>(
  array: TItem[],
  callback: (item: TItem) => TResult | undefined,
  index = 0
): TResult | undefined {
  if (index >= array.length) {
    return undefined
  }

  const result = callback(array[index])

  if (result === undefined) {
    return iterateUntilResult(array, callback, index + 1)
  }

  if (isPromise(result)) {
    return result.then(value => {
      if (value === undefined) {
        return iterateUntilResult(array, callback, index + 1)
      }
      return value
    }) as any
  }

  return result
}