Function doWhileAsync

Performs a while loop, calling the provided callbackFn function until the state.isDone property is set to true or the optional isDOneFn returns true. The callback function will receive a single state argument and may return either a value or a promise, if a promise is returned the while loop will wait until the promise is resolved before calling the callback function again. If the callback function never returns a promise the while loop will be executed synchronous and last value returned by the callback will be returned, if the callback function returns a promise the while loop will be asynchronous and an IPromise will be returned and resolved with the last value returned by the callback or rejected if the callback promise rejects or throws an error.

Since

0.5.0

Remarks

• If an isDoneFn is provided the state.isDone property will be set to the provided value and is accessible withing the callback function. The callbackFn may overwrite the value of the state.isDone property within the callback function with a boolean value or another function that returns a boolean value.
• The callback function is called until until the state.isDone property is set to true or if state.isDone is a function until the function returns `true.
• The callback function will receive a single {@link IWhileState state} argument that contains the following properties:
• iter - The zero-based iteration count, which is incremented after each call to the callbackFn and any isDone function (if provided), the iter property is accessible withing the callback function and may be overwritten within the callback function.
• res - The last resolved result value returned by the callbackFn function.
• isDone - A boolean value or a callback function that will be called to check if the while loop should stop, the isDone property is accessible withing the callback function and may be overwritten within the callback function.
• The callback function may return either a value or a promise, if a promise is returned the while loop will wait until the promise is resolved before calling the callback function again.
• If the callback function throws an error when executing synchronously the exception will also be thrown synchronously otherwise the returned promise will be rejected with the error. @example

// Synchronous example
const result = doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function
   if (state.idx < 10) {
     // Logs each iteration index (will be called synchronously)
     // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
     console.log(state.idx);
  } else {
    state.isDone = true;
    return "Hello";
 }
});

console.log(result); // returns Hello after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

// Synchronous example with isDoneFn
const result = doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function
   if (state.idx < 10) {
     // Logs each iteration index (will be called synchronously)
     // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
     console.log(state.idx);
  } else {
    return "Hello";
 }
}, (state) => state.idx > 10);
console.log(result); // returns Hello after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

// Asynchronous examples
const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function
  if (state.idx < 10) {
    // Logs each iteration index
    // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 calling the callback function synchronously
    console.log(state.idx);
    // Returning a promise will cause `doWhileAsync` to return a promise to the caller
    // and wait for the promise to resolve before calling the callback function again.
    return createTimeoutPromise(10, true, state.idx);
  }

  state.isDone = true;
  return createResolvedPromise("Darkness");
});
console.log(result); // Darkness

// Asynchronous example with isDoneFn
const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function
  if (state.idx < 10) {
    // Logs each iteration index
    // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 calling the callback function synchronously
    console.log(state.idx);
    // Returning a promise will cause `doWhileAsync` to return a promise to the caller
    // and wait for the promise to resolve before calling the callback function again.
    return createTimeoutPromise(10, true, state.idx);
  }

  return createResolvedPromise("Darkness");
}, (state) => state.idx > 10);
console.log(result); // returns Darkness after logging 0, 1, 2, 3, 4, 5, 6, 7, 8, 9

// Combination Synchronous and Asynchronous example
const result = await doWhileAsync((state) => { // Note: DO NOT use async here unless you use await withing the function
  if (state.idx < 10) {
    // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    // Logs each iteration index (will be called synchronously)
    console.log(state.idx);
  } else {
    state.isDone = true;
    // Returning a promise will cause `doWhileAsync` to return a promise to the caller
    // and wait for the promise to resolve before resolving the returned promise.
    return createResolvedPromise("my old friend");
  }
});

console.log(result); // my old friend

// Asynchronous example using await
const result = await doWhileAsync(async (state) => {
  if (state.idx < 10) {
    // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    // Logs each iteration index (will be called synchronously)
    await createTimeoutPromise(10, true, state.idx);
  } else {
    state.isDone = true;
    // Returning a promise will cause `doWhileAsync` to return a promise to the caller
    // and wait for the promise to resolve before resolving the returned promise.
    return await createResolvedPromise("my old friend");
  }
});

console.log(result); // my old friend

// Asynchronous example using await and dynamically setting the isDone function
const result = await doWhileAsync(async (state) => {
  // dynamically set the isDone function
  if (state.idx < 10) {
    state.isDone = () => return false;
    // Logs 0, 1, 2, 3, 4, 5, 6, 7, 8, 9
    // Logs each iteration index (will be called synchronously)
    await createTimeoutPromise(10, true, state.idx);
  } else {
    state.isDone = () => return true;
    // Returning a promise will cause `doWhileAsync` to return a promise to the caller
    // and wait for the promise to resolve before resolving the returned promise.
    return await createResolvedPromise("my old friend");
  }
});

console.log(result); // my old friend
Copy