feat: Add support for a cancel-able timeout. (#476)

The current timedPromise doesn't provide access to the handle, so it
cannot cancel the timer. The timer itself will not have a harmful
result, but it is an open handle. Open handles often prevent runtimes
from exiting. For instance initializing something like the node server
with a really long timeout may keep the process open for that entire
timeout even if the SDK initialized.

I am adding this as a new function, which node server will then migrate
to. RN can of course migrate as well, but this change will be
independent.

I noticed this unit testing the openfeature-node-provider with a timeout
and each test had a remaining open handle.

---------

Co-authored-by: Matthew M. Keeler <[email protected]>

Author: kinyoklion

packages/shared/common/__tests__/cancelableTimeoutPromise.test.ts

@@ -0,0 +1,53 @@
+import { LDTimeoutError } from '../src/errors';
+import { cancelableTimedPromise } from '../src/utils/cancelableTimedPromise';
+
+it('throws when it times out', async () => {
+  try {
+    await cancelableTimedPromise(0.1, 'test-task').promise;
+    fail('timeout did not fire');
+  } catch (err) {
+    expect(err).toBeInstanceOf(LDTimeoutError);
+  }
+});
+
+it('promise resolves when cancelled', async () => {
+  // This test would take many minutes if the cancellation didn't work.
+  const cancelableTimeout = cancelableTimedPromise(300, 'test-task');
+  cancelableTimeout.cancel();
+  await cancelableTimeout.promise;
+});
+
+it('can be used for timing out a task', async () => {
+  const cancelableTimeout = cancelableTimedPromise(0.1, 'exampleTimeout');
+  let timeout: ReturnType<typeof setTimeout>;
+  const sampleTask = new Promise<void>((resolve, _reject) => {
+    timeout = setTimeout(() => resolve, 1000);
+  });
+
+  try {
+    await Promise.race([sampleTask, cancelableTimeout.promise]);
+    fail('timeout did not fire');
+  } catch (err) {
+    expect(err).toBeInstanceOf(LDTimeoutError);
+  }
+  // @ts-ignore
+  clearTimeout(timeout);
+});
+
+it('a raced promise can cancel the task', async () => {
+  const cancelableTimeout = cancelableTimedPromise(1000, 'exampleTimeout');
+  const sampleTask = new Promise<void>((resolve, _reject) => {
+    setTimeout(resolve, 100);
+  });
+
+  try {
+    await Promise.race([
+      sampleTask.then(() => {
+        cancelableTimeout.cancel();
+      }),
+      cancelableTimeout.promise,
+    ]);
+  } catch (err) {
+    fail('should not have timed out');
+  }
+});

packages/shared/common/src/utils/cancelableTimedPromise.ts

@@ -0,0 +1,39 @@
+import { LDTimeoutError } from '../errors';
+import { VoidFunction } from './VoidFunction';
+
+/**
+ * Represents a timeout that can be cancelled.
+ *
+ * When racing a timeout, and another task completes before the timeout,
+ * then the timeout should be cancelled. This prevents leaving open handles
+ * which can stop the runtime from exiting.
+ */
+export interface CancelableTimeout {
+  promise: Promise<void>;
+  cancel: VoidFunction;
+}
+
+/**
+ * Returns a promise which errors after t seconds.
+ *
+ * @param t Timeout in seconds.
+ * @param taskName Name of task being timed for logging and error reporting.
+ */
+export function cancelableTimedPromise(t: number, taskName: string): CancelableTimeout {
+  let timeout: ReturnType<typeof setTimeout>;
+  let resolve: VoidFunction;
+  const promise = new Promise<void>((_res, reject) => {
+    resolve = _res;
+    timeout = setTimeout(() => {
+      const e = `${taskName} timed out after ${t} seconds.`;
+      reject(new LDTimeoutError(e));
+    }, t * 1000);
+  });
+  return {
+    promise,
+    cancel: () => {
+      resolve();
+      clearTimeout(timeout);
+    },
+  };
+}

packages/shared/common/src/utils/index.ts

@@ -1,3 +1,4 @@
+import { cancelableTimedPromise, type CancelableTimeout } from './cancelableTimedPromise';
 import clone from './clone';
 import { secondsToMillis } from './date';
 import debounce from './debounce';
@@ -24,4 +25,6 @@ export {
   sleep,
   timedPromise,
   VoidFunction,
+  type CancelableTimeout,
+  cancelableTimedPromise,
 };