kerosene: Add Deferred class

packages/kerosene-test/package.json

@@ -46,7 +46,7 @@
     "utils"
   ],
   "dependencies": {
-    "@kablamo/kerosene": "^0.0.28",
+    "@kablamo/kerosene": "^0.0.29",
     "@types/lodash": "^4.14.184",
     "@types/sinon": "^10.0.13",
     "lodash": "^4.17.21",

packages/kerosene-ui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene-ui",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene-ui",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"
@@ -22,7 +22,7 @@
   },
   "dependencies": {
     "@babel/runtime": "^7.18.9",
-    "@kablamo/kerosene": "^0.0.28",
+    "@kablamo/kerosene": "^0.0.29",
     "@types/lodash": "^4.14.184",
     "lodash": "^4.17.21"
   },

packages/kerosene/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kablamo/kerosene",
-  "version": "0.0.28",
+  "version": "0.0.29",
   "repository": "https://github.com/KablamoOSS/kerosene/tree/master/packages/kerosene",
   "bugs": {
     "url": "https://github.com/KablamoOSS/kerosene/issues"

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;
+    });
+  }
+}