Improve comment and type signature

Author: Alex Birdsall

airbyte-webapp/src/core/request/pollUntil.ts

@@ -1,20 +1,31 @@
-import { timer, delay, from, concatMap, takeWhile, last, raceWith, lastValueFrom, NEVER } from "rxjs";
+import { concatMap, delay, from, last, lastValueFrom, raceWith, takeWhile, timer, NEVER } from "rxjs";
 
-// Known issues:
-// - the case where `apiFn` returns `false` and `condition(false) === true` is impossible to distinguish from a timeout
+/**
+ * Repeatedly calls `apiFn` every `interval` milliseconds, until either `conditionFn`
+ * returns `true` or `options.maxTimeout` milliseconds have elapsed. Returns a Promise
+ * which resolves to `false` if `options.maxTimout` is reached or the value of `apiFn`
+ * which passes the condition otherwise. If no `options.maxTimeout` is specified, it will
+ * continue polling indefinitely until a matching value is found, so let's try not to DDOS
+ * ourselves.
+ *
+ * Known issues:
+ * - the case where `apiFn` returns `false` and `conditionFn(false) === true` is impossible
+ *   to distinguish from a timeout, so don't poll for a boolean without first wrapping it
+ *   with something like `.then(bool => ({ hopefullyUsefulFieldName: bool }))`.
+ */
 export function pollUntil<ResponseType>(
   apiFn: () => Promise<ResponseType>,
-  condition: (res: ResponseType) => boolean,
+  conditionFn: (res: ResponseType) => boolean,
   options: { interval: number; maxTimeout?: number }
-) {
+): Promise<ResponseType | false> {
   const { interval, maxTimeout } = options;
   const poll$ = timer(0, interval).pipe(
-    concatMap((_) => from(apiFn())),
-    takeWhile((result) => !condition(result), true),
-    last()
+    concatMap((_) => from(apiFn())), // combine all emitted values into a single stream
+    takeWhile((result) => !conditionFn(result), true),
+    last() // only emit the latest polled value
   );
 
-  const timeout$ = maxTimeout ? from([false]).pipe(delay(maxTimeout)) : NEVER;
+  const timeout$ = maxTimeout ? from([false] as Array<false>).pipe(delay(maxTimeout)) : NEVER;
 
   return lastValueFrom(poll$.pipe(raceWith(timeout$)));
 }