Bump braces from 3.0.2 to 3.0.3

Bumps [braces](https://github.com/micromatch/braces) from 3.0.2 to 3.0.3.
- [Changelog](https://github.com/micromatch/braces/blob/master/CHANGELOG.md)
- [Commits](https://github.com/micromatch/braces/compare/3.0.2...3.0.3)

---
updated-dependencies:
- dependency-name: braces
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>

README.md

@@ -8,7 +8,7 @@ Simple but effective way to rate limit Tasks in JavaScript. Anything can be rate
 
 ## Usage
 ```js
-var RateLimiter = require("@xaymar/ratelimiter");
+var { RateLimiter } = require("@xaymar/ratelimiter");
 
 let limitMany = new RateLimiter(4);
 let limitOne = new RateLimiter(1);
@@ -40,7 +40,7 @@ No, but it is relatively easy to do without official support. See the example be
 
 ```js
 // main.js
-var RateLimiter = require("@xaymar/ratelimiter");
+var { RateLimiter } = require("@xaymar/ratelimiter");
 
 let worker = new Worker("worker.js");
 let workerRL = new RateLimiter(1);

package.json

@@ -4,7 +4,7 @@
   "description": "A simple but effective way to rate limit Tasks in JavaScript.",
   "license": "GPLv3",
   "repository": "https://github.com/Xaymar/js-ratelimiter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "funding": {
 	"type": "patreon",
 	"url": "https://www.patreon.com/xaymar"
@@ -16,7 +16,7 @@
     "compile": "npx tsc",
     "build": "npm run fix && npm run compile",
 	"prepublish": "npm run build",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "test": "node ./tests/test.js"
   },
   "devDependencies": {
     "@types/express": "^4.17.17",

source/ratelimiter.ts

@@ -28,11 +28,18 @@ type RateLimiterAsyncExecutor = (...args: any[]) => Promise<any>;
 type RateLimiterSyncExecutor = (...args: any[]) => any;
 type RateLimiterExecutor = RateLimiterSyncExecutor | RateLimiterAsyncExecutor;
 
-export default class RateLimiter {
+/** A simple but effective way to rate limit Tasks.
+ *
+ */
+export class RateLimiter {
 	private _maximum: number = 0;
 	private _available: number = 0;
 	private _instances: any[];
 
+	/** Create a new instance of a RateLimiter.
+	 *
+	 * @param limit The maximum number of tasks that should run in parallel. The Default is 2/3rds of the available CPU threads.
+	 */
 	constructor(limit?: number) {
 		if (!limit) {
 			this._maximum = Math.ceil(Math.max(1, os.cpus().length / 3 * 2));
@@ -43,6 +50,12 @@ export default class RateLimiter {
 		this._instances = [];
 	}
 
+	/** Queue up a new task.
+	 *
+	 * @param executor The function that should be run eventually.
+	 * @param args Optional arguments to pass to the function.
+	 * @returns A Promise that resolves with the result of the function.
+	 */
 	async queue(executor: RateLimiterExecutor, ...args: any[]) {
 		// Use async/await to find a free slot.
 		while (this._available == 0) {

tests/test.js

@@ -0,0 +1,119 @@
+// May require `npm link`.
+const { RateLimiter } = require("../generated/ratelimiter");
+
+async function asyncRunTest(fn, ...args) {
+	try {
+		let msg = await fn(...args);
+		if (msg) {
+			console.log(`✅ ${fn.name}(${args}): ${msg}`);
+		} else {
+			console.log(`✅ ${fn.name}(${args})`);
+		}
+	} catch (ex) {
+		console.log(`❌ ${fn.name}(${args})`)
+		console.error(ex);
+		process.exitCode++;
+	}
+}
+function runTest(fn, ...args) {
+	try {
+		let msg = fn(...args);
+		if (msg) {
+			console.log(`✅ ${fn.name}(${args}): ${msg}`);
+		} else {
+			console.log(`✅ ${fn.name}(${args})`);
+		}
+	} catch (ex) {
+		console.log(`❌ ${fn.name}(${args})`);
+		console.error(ex);
+		process.exitCode++;
+	}
+}
+async function delay(time) {
+	await new Promise((resolve, reject) => {
+		setTimeout(() => {
+			resolve();
+		}, time);
+	});
+}
+
+function test_Construct(limit) {
+	let rl = new RateLimiter(limit);
+}
+
+async function test_TaskLimit(tasks, limit) {
+	let rl = new RateLimiter(limit);
+	let p = new Array();
+	for (let idx = 0; idx < tasks; idx++) {
+		p.push(rl.queue(() => {
+			return true;
+		}));
+	}
+
+	let r = await Promise.all(p);
+	for (res of r) {
+		if (res !== true) {
+			throw new Error("Result is unexpected.");
+		}
+	}
+}
+
+async function test_LimitEnforcement(tasks, limit) {
+	let rl = new RateLimiter(limit);
+	let value = 0;
+	let time = 50;
+
+	let records = [];
+	let t = setInterval(() => {
+		records.push([
+			value, Date.now()
+		]);
+	}, 25);
+
+	let p = new Array();
+	for (let idx = 0; idx < tasks; idx++) {
+		p.push(rl.queue(async () => {
+			await delay(time);
+			value++;
+		}));
+	}
+	await Promise.all(p);
+
+	clearInterval(t);
+
+	let totalTime = 0;
+	let totalValue = 0;
+	for (let n = 1; n < records.length; n++) {
+		let pRecord = records[n - 1];
+		let cRecord = records[n];
+
+		let deltaTime = cRecord[1] - pRecord[1];
+		let deltaValue = cRecord[0] - pRecord[0];
+
+		totalTime += deltaTime;
+		totalValue += deltaValue;
+	}
+	let averageChange = totalValue / totalTime;
+	let normalizedChange = averageChange * time;
+	// setTimeout loses accuracy over time, not sure what the solution is. Accepting +-1 for now.
+	if ((normalizedChange < (limit - 1.)) || (normalizedChange > (limit + 1.))) {
+		throw new Error(`Outside acceptable range (${normalizedChange} is not equal to ${limit}).`);
+	} else {
+		return `Within acceptable range (${normalizedChange} is roughly equal to ${limit}).`
+	}
+}
+
+(async function() {
+	process.exitCode = 0;
+	for (let limit = 1; limit <= 64; limit *= 2) {
+		runTest(test_Construct, limit);
+	}
+	for (let limit = 1; limit <= 10; limit++) {
+		for (let tasks = 1; tasks <= 64; tasks *= 2) {
+			await asyncRunTest(test_TaskLimit, tasks, limit);
+		}
+	}
+	for (let limit = 1; limit <= 10; limit++) {
+		await asyncRunTest(test_LimitEnforcement, 100, limit);
+	}
+})();