From ce055fa4c52cdbdd96ff061e5a810c48ef8e9631 Mon Sep 17 00:00:00 2001
From: Sven Slootweg <admin@cryto.net>
Date: Tue, 23 Apr 2019 21:37:16 +0200
Subject: [PATCH] Initial commit

---
 .gitignore   |  2 ++
 README.md    | 44 ++++++++++++++++++++++++++++++++++++++++++++
 example.js   | 22 ++++++++++++++++++++++
 index.js     | 16 ++++++++++++++++
 package.json | 11 +++++++++++
 5 files changed, 95 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..254e3d4
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,2 @@
+yarn.lock
+node_modules
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1d7ca30
--- /dev/null
+++ b/README.md
@@ -0,0 +1,44 @@
+# @joepie91/promise-delay-since
+
+A function that, when called, produces a Promise that resolves a specified amount of milliseconds since a particular timestamp - or immediately, if the delay since that timestamp has already passed.
+
+This is particularly useful when implementing rate-limiting and/or task distribution code - your implementation only has to track the timestamp of the last call, and leave it up to this module to decide when to resolve a Promise that kickstarts the next task.
+
+## Example
+
+See also `example.js` for a runnable version. This example uses Bluebird for `Promise.try` (read [this article](http://cryto.net/~joepie91/blog/2016/05/11/what-is-promise-try-and-why-does-it-matter/) to understand why), but Bluebird is not required to use this module.
+
+```js
+"use strict";
+
+const Promise = require("bluebird");
+const promiseDelaySince = require("@joepie91/promise-delay-since");
+
+let startTimestamp = Date.now();
+
+Promise.try(() => {
+	// Logs immediately after running
+	console.log("Hello world 1");
+	
+	return promiseDelaySince(startTimestamp, 2000);
+}).then(() => {
+	// Logs 2 seconds after running
+	console.log("Hello world 2");
+	
+	return promiseDelaySince(startTimestamp, 3000);
+}).then(() => {
+	// Logs 3 seconds after running
+	console.log("Hello world 3");
+});
+```
+
+## API
+
+### promiseDelaySince(sinceTimestamp, delay)
+
+Creates a new Promise that will resolve `delay` milliseconds from the specified `sinceTimestamp`. If the current time is later than `sinceTimestamp + delay`, the returned Promise will resolve immediately.
+
+- __sinceTimestamp:__ The reference timestamp to start counting from, as a 'UNIX timestamp' in milliseconds (like you get from `Date.now()`).
+- __delay:__ The delay as a number, in milliseconds.
+
+The Promise will never reject.
\ No newline at end of file
diff --git a/example.js b/example.js
new file mode 100644
index 0000000..d89e34c
--- /dev/null
+++ b/example.js
@@ -0,0 +1,22 @@
+"use strict";
+
+const Promise = require("bluebird");
+
+const promiseDelaySince = require("./");
+
+let startTimestamp = Date.now();
+
+Promise.try(() => {
+	// Logs immediately after running
+	console.log("Hello world 1");
+	
+	return promiseDelaySince(startTimestamp, 2000);
+}).then(() => {
+	// Logs 2 seconds after running
+	console.log("Hello world 2");
+	
+	return promiseDelaySince(startTimestamp, 3000);
+}).then(() => {
+	// Logs 3 seconds after running
+	console.log("Hello world 3");
+});
\ No newline at end of file
diff --git a/index.js b/index.js
new file mode 100644
index 0000000..3b92c2f
--- /dev/null
+++ b/index.js
@@ -0,0 +1,16 @@
+"use strict";
+
+module.exports = function promiseDelaySince(previousTimestamp, delay) {
+	return new Promise((resolve, reject) => {
+		let targetTime = previousTimestamp + delay;
+		let currentTime = Date.now();
+
+		if (currentTime > targetTime) {
+			resolve();
+		} else {
+			setTimeout(() => {
+				resolve();
+			}, targetTime - currentTime);
+		}
+	});
+};
\ No newline at end of file
diff --git a/package.json b/package.json
new file mode 100644
index 0000000..052929a
--- /dev/null
+++ b/package.json
@@ -0,0 +1,11 @@
+{
+  "name": "@joepie91/promise-delay-since",
+  "version": "1.0.0",
+  "main": "index.js",
+  "repository": "git@git.cryto.net:joepie91/node-promise-delay-since.git",
+  "author": "Sven Slootweg <admin@cryto.net>",
+  "license": "WTFPL OR CC0-1.0",
+  "devDependencies": {
+    "bluebird": "^3.5.4"
+  }
+}