Merge 858747d into 89d714e

packages/kerosene/readme.md

@@ -160,6 +160,10 @@ Returns the provided `value` rounded to the number of significant `figures` prov
 
 ## Promise
 
+### `Deferred`
+
+Deferred is a class that allows a Promise to be created in advance of the code that will `resolve`/`reject` it.
+
 ### `mapSeries(items, iteratee)`
 
 Maps over `items` with a promise-returning `iteratee` in series.

packages/kerosene/src/index.ts

@@ -26,6 +26,7 @@ export { default as toDegrees } from "./math/toDegrees";
 export { default as toRadians } from "./math/toRadians";
 export { default as toSignificantFigures } from "./math/toSignificantFigures";
 
+export { default as Deferred } from "./promise/Deferred";
 export { default as mapSeries } from "./promise/mapSeries";
 
 export * from "./string";

packages/kerosene/src/promise/Deferred.spec.ts

@@ -0,0 +1,20 @@
+import timeout from "../function/timeout";
+import Deferred from "./Deferred";
+
+describe("Deferred", () => {
+  it("should allow a Promise to be created and resolved", async () => {
+    const deferred = new Deferred<boolean>();
+    deferred.resolve(true);
+
+    await expect(deferred.promise).resolves.toBe(true);
+  });
+
+  it("should allow a Promise to be created and reject", async () => {
+    const deferred = new Deferred();
+    const error = new Error("an error");
+    // Promise must be rejected _after_ a catch handler has been attached or we will see UnhandledPromiseRejection from Node
+    timeout(0).then(() => deferred.reject(error));
+
+    await expect(deferred.promise).rejects.toBe(error);
+  });
+});

packages/kerosene/src/promise/Deferred.ts

@@ -0,0 +1,19 @@
+import type { Mutable } from "../types";
+
+/**
+ * Deferred is a class that allows a Promise to be created in advance of the code that will `resolve`/`reject` it.
+ */
+export default class Deferred<T> {
+  public readonly promise: Promise<T>;
+
+  public readonly resolve!: (value: T) => void;
+
+  public readonly reject!: (reason?: unknown) => void;
+
+  constructor() {
+    this.promise = new Promise<T>((resolve, reject) => {
+      (this as Mutable<typeof this>).resolve = resolve;
+      (this as Mutable<typeof this>).reject = reject;
+    });
+  }
+}