@ericcornelissen/assert-time 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-2026 Eric Cornelissen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,63 @@
+# `assert-time`
+
+Assert the duration of a (blocking or async) function under test.
+
+Note that blocking tests still block the event loop, it is just asserted that
+it did not take longer than expected.
+
+## Usage
+
+### Generic Example
+
+```javascript
+var assertTime = require('@ericcornelissen/assert-time');
+
+var fut = require('./index.js');
+
+// will throw if slow
+assertTime(fut, 100);
+
+// will call onSlow or onTime
+assertTime(
+  fut,
+  100,
+  function onSlow(duration) {
+    // ...
+  },
+  function onTime(duration) {
+    // ...
+  }
+);
+```
+
+### [Tape]
+
+```javascript
+var test = require('tape');
+var assertTime = require('@ericcornelissen/assert-time');
+
+var fut = require('./index.js');
+
+test('timing test #1', function (t) {
+  t.doesNotThrow(function () {
+    assertTime(fut, timeout);
+  });
+  t.end();
+});
+
+test('timing test #2', function (t) {
+  assertTime(
+    fut,
+    100,
+    function onSlow(duration) {
+      t.fail('Test timed out after ' + duration + 'ms');
+      t.end();
+    },
+    function onTime() {
+      t.end();
+    }
+  );
+});
+```
+
+[tape]: https://www.npmjs.com/package/tape

package/index.js

@@ -0,0 +1,75 @@
+// SPDX-License-Identifier: MIT
+
+/**
+ * @param {Function} fut The function under test.
+ * @param {number} timeout The maximum runtime of `fn` in milliseconds.
+ * @param {function(number): void} [onSlow] The function called if `fn`'s runtime exceeds `timeout`, receives the runtime in milliseconds.
+ * @param {function(number): void} [onTime] The function called if `fn`'s runtime is within `timeout`, receives the runtime in milliseconds.
+ * @throws {number | undefined | Promise<number> | Promise<undefined>} If `onSlow` is not provied `fn`'s duration, otherwise `undefined`.
+ * @throws {Error} If `onSlow` is not provied `fn`'s duration exceeds `timeout`.
+ */
+function assertTime(fut, timeout, onSlow, onTime) {
+	var t1, t2, duration;
+	var timedOut = false;
+
+	if (typeof onSlow === 'function') {
+		t1 = setTimeout(function () {
+			timedOut = true;
+
+			clearTimeout(t2);
+			onSlow(duration || timeout);
+		}, timeout);
+	}
+
+	var start = Date.now();
+	const result = fut();
+	if (typeof onSlow === 'function') {
+		if (isPromise(result)) {
+			result.then(function () {
+				duration = Date.now() - start;
+				if (!timedOut) {
+					clearTimeout(t1);
+					onTime(duration);
+        }
+
+        return undefined;
+			});
+		} else {
+			duration = Date.now() - start;
+			t2 = setTimeout(function () {
+				if (duration < timeout) {
+					clearTimeout(t1);
+					onTime(duration);
+				}
+			}, 0);
+		}
+	} else {
+		if (isPromise(result)) {
+			return result.then(function () {
+				duration = Date.now() - start;
+				if (duration > timeout) {
+					throw new Error('Timeout of ' + timeout + 'ms exceeded (took ' + duration + 'ms)');
+				} else {
+					return duration;
+				}
+			});
+		} else {
+			duration = Date.now() - start;
+			if (duration > timeout) {
+				throw new Error('Timeout of ' + timeout + 'ms exceeded (took ' + duration + 'ms)');
+			} else {
+				return duration;
+			}
+		}
+	}
+}
+
+function isPromise(v) {
+	try {
+		return v instanceof Promise;
+	} catch (_) {
+		return false;
+	}
+}
+
+module.exports = assertTime;

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ericcornelissen/assert-time",
+  "version": "1.0.0",
+  "description": "assert the duration of a (blocking or async) function under test",
+  "type": "commonjs",
+  "license": "MIT",
+  "author": {
+    "name": "Eric Cornelissen",
+    "email": "ericornelissen@gmail.com",
+    "url": "https://ericcornelissen.dev/"
+  },
+  "engines": {
+    "node": ">=0.8.28"
+  },
+  "exports": {
+    ".": "./index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ericcornelissen/node-assert-time.git"
+  },
+  "scripts": {
+    "example:mocha": "mocha example-mocha.js",
+    "example:tape": "node example-tape.js",
+    "test": "node test.js",
+    "test:compatibility": "nve 0.8.28,0.10.31,0.12.0,4.0.0,5.0.0,6.0.0,7.0.0,8.0.0,9.0.0,10.0.0,11.0.0,12.0.0,13.0.0,14.0.0,15.0.0,16.0.0,17.0.0,18.0.0,19.0.0,20.0.0,21.0.0,22.0.0,23.0.0,24.0.0,25.0.0,26.0.0 node test.js"
+  },
+  "devDependencies": {
+    "mocha": "11.7.6",
+    "nve": "18.0.3",
+    "tape": "5.9.0"
+  }
+}