From 5521a58a9f7eec882d294e7cde7f0c32adcea64e Mon Sep 17 00:00:00 2001
From: Sven Slootweg <admin@cryto.net>
Date: Wed, 19 Jun 2024 01:50:20 +0200
Subject: [PATCH] Initial version

---
 .gitignore   |  1 +
 README.md    | 33 +++++++++++++++++++++++++++++++++
 example.js   | 14 ++++++++++++++
 index.js     | 16 ++++++++++++++++
 package.json | 17 +++++++++++++++++
 5 files changed, 81 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 example.js
 create mode 100644 index.js
 create mode 100644 package.json

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..3c3629e
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1 @@
+node_modules
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ff9b194
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+# promise-defer
+
+Small utility function to create a defer; that is, a Promise which can be externally resolved or rejected.
+
+__You should not use this unless you have no other option.__ Typically that means you are implementing an asynchronous queue of some sort. This is *not* an appropriate tool to use for typical asynchronous/Promises code; not even for most cases where you need to promisify something - in those cases you should use `new Promise` instead.
+
+This module should strictly be used for cases where the resolution and rejection *have* to be implemented separately from the Promise itself due to architectural constraints that cannot be solved otherwise, and you need to make sure that you fully understand the implications that this has for eg. error handling. If you're not sure what this means, you should not use this module.
+
+## Example
+
+```js
+"use strict";
+
+const promiseDefer = require("./");
+
+let { resolve, reject, promise } = promiseDefer();
+
+(async function () {
+	await promise;
+	console.log("resolved!");
+})();
+
+setTimeout(() => {
+	resolve();
+}, 1000);
+
+```
+
+## API
+
+### promiseDefer()
+
+__Returns:__ An object with `{ promise, resolve, reject }` keys. The `promise` is the generated Promise for this defer, whereas `resolve` and `reject` are respectively the functions for resolving and rejecting that Promise.
diff --git a/example.js b/example.js
new file mode 100644
index 0000000..bfab40b
--- /dev/null
+++ b/example.js
@@ -0,0 +1,14 @@
+"use strict";
+
+const promiseDefer = require("./");
+
+let { resolve, reject, promise } = promiseDefer();
+
+(async function () {
+	await promise;
+	console.log("resolved!");
+})();
+
+setTimeout(() => {
+	resolve();
+}, 1000);
diff --git a/index.js b/index.js
new file mode 100644
index 0000000..66a040b
--- /dev/null
+++ b/index.js
@@ -0,0 +1,16 @@
+"use strict";
+
+module.exports = function promiseDefer() {
+	let rej_, res_;
+
+	let promise = new Promise((resolve, reject) => {
+		rej_ = reject;
+		res_ = resolve;
+	});
+
+	return {
+		resolve: res_,
+		reject: rej_,
+		promise: promise
+	};
+};
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..8098f39
--- /dev/null
+++ b/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "@joepie91/promise-defer",
+  "version": "1.0.0",
+  "description": "Small utility function for creating a defer",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "example.js",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": ["promise", "async", "defer"],
+  "author": "Sven Slootweg <admin@cryto.net>",
+  "license": "WTFPL OR CC0-1.0"
+}