@oscarpalmer/atoms 0.131.0 → 0.133.0

package/dist/atoms.full.js

@@ -1971,6 +1971,239 @@ function round(value, decimals) {
 function sum(array, key) {
 	return getAggregated("sum", array, key);
 }
+var PromiseTimeoutError = class extends Error {
+	constructor() {
+		super(MESSAGE_TIMEOUT);
+		this.name = NAME;
+	}
+};
+/**
+* Create a delayed promise that resolves after a certain amount of time
+* @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+* @returns A promise that resolves after the delay
+*/
+function delay(time) {
+	return new Promise((resolve) => setTimeout(resolve, getNumberOrDefault$1(time)));
+}
+function getBooleanOrDefault$1(value, defaultValue) {
+	return typeof value === "boolean" ? value : defaultValue;
+}
+function getNumberOrDefault$1(value) {
+	return typeof value === "number" ? value : 0;
+}
+async function promises(items, eager) {
+	const actual = items.filter((item) => item instanceof Promise);
+	if (actual.length === 0) return actual;
+	const isEager = getBooleanOrDefault$1(eager, false);
+	const { length } = actual;
+	const data = {
+		last: length - 1,
+		result: []
+	};
+	let handlers;
+	return new Promise((resolve, reject) => {
+		handlers = {
+			reject,
+			resolve
+		};
+		for (let index = 0; index < length; index += 1) actual[index].then((value) => resolveResult(index, data, handlers, value, isEager)).catch((reason) => rejectResult(index, data, handlers, reason, isEager));
+	});
+}
+function rejectResult(index, data, handlers, reason, eager) {
+	if (eager) handlers.reject(reason);
+	else {
+		data.result[index] = {
+			status: TYPE_REJECTED,
+			reason
+		};
+		if (index === data.last) handlers.resolve(data.result);
+	}
+}
+function resolveResult(index, data, handlers, value, eager) {
+	data.result[index] = eager ? value : {
+		status: TYPE_FULFILLED,
+		value
+	};
+	if (index === data.last) handlers.resolve(data.result);
+}
+function timed(promise, timeout) {
+	if (!(promise instanceof Promise)) throw new TypeError(MESSAGE_EXPECTATION);
+	if (getNumberOrDefault$1(timeout) <= 0) return promise;
+	return Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new PromiseTimeoutError()), timeout))]);
+}
+const MESSAGE_EXPECTATION = "Timed function expected a Promise";
+const MESSAGE_TIMEOUT = "Promise timed out";
+const NAME = "PromiseTimeoutError";
+const TYPE_FULFILLED = "fulfilled";
+const TYPE_REJECTED = "rejected";
+var Queue = class {
+	#callback;
+	#handled = [];
+	#id = 0;
+	#items = [];
+	#options;
+	#paused;
+	#runners = 0;
+	/**
+	* Is the queue active?
+	*/
+	get active() {
+		return this.#runners > 0;
+	}
+	/**
+	* Is the queue empty?
+	*/
+	get empty() {
+		return this.#items.length === 0;
+	}
+	/**
+	* Is the queue full?
+	*/
+	get full() {
+		return this.#options.maximum > 0 && this.#items.length >= this.#options.maximum;
+	}
+	/**
+	* Is the queue paused?
+	*/
+	get paused() {
+		return this.#paused;
+	}
+	/**
+	* Number of items in the queue
+	*/
+	get size() {
+		return this.#items.length;
+	}
+	constructor(callback, options) {
+		this.#callback = callback;
+		this.#options = options;
+		this.#paused = !options.autostart;
+	}
+	/**
+	* Add an item to the queue
+	* @param parameters Parameters to use when item runs
+	* @returns Queued item
+	*/
+	add(...parameters) {
+		if (this.full) throw new QueueError(MESSAGE_MAXIMUM);
+		let rejector;
+		let resolver;
+		const id = this.#identify();
+		const promise = new Promise((resolve, reject) => {
+			rejector = reject;
+			resolver = resolve;
+		});
+		this.#items.push({
+			id,
+			parameters,
+			promise,
+			reject: rejector,
+			resolve: resolver
+		});
+		if (this.#options.autostart) this.#run();
+		return {
+			id,
+			promise
+		};
+	}
+	/**
+	* Remove and reject all items in the queue
+	*/
+	clear() {
+		const items = this.#items.splice(0);
+		const { length } = items;
+		for (let index = 0; index < length; index += 1) items[index].reject(new QueueError(MESSAGE_CLEAR));
+	}
+	/**
+	* Pause the queue
+	*
+	* - Currently running items will not be stopped
+	* - New added items will not run until the queue is resumed
+	*/
+	pause() {
+		this.#paused = true;
+	}
+	/**
+	* Remove and reject a specific item in the queue
+	* @param id ID of queued item
+	*/
+	remove(id) {
+		const index = this.#items.findIndex((item) => item.id === id);
+		if (index > -1) {
+			const [item] = this.#items.splice(index, 1);
+			item.reject(new QueueError(MESSAGE_REMOVE));
+		}
+	}
+	/**
+	* Resume the queue
+	*/
+	resume() {
+		if (this.#paused) {
+			const handled = this.#handled.splice(0);
+			const { length } = handled;
+			for (let index = 0; index < length; index += 1) handled[index]();
+		}
+		this.#paused = false;
+		const length = Math.min(this.#options.concurrency, this.#items.length);
+		for (let index = 0; index < length; index += 1) this.#run();
+	}
+	#identify() {
+		this.#id += 1;
+		return this.#id;
+	}
+	async #run() {
+		if (this.#paused || this.#runners >= this.#options.concurrency) return;
+		this.#runners += 1;
+		let item = this.#items.shift();
+		while (item != null) {
+			let handler;
+			let result;
+			try {
+				result = await this.#callback(...item.parameters);
+				handler = item.resolve;
+			} catch (thrown) {
+				result = thrown;
+				handler = item.reject;
+			}
+			if (this.#paused) {
+				this.#handled.push(() => handler(result));
+				break;
+			}
+			handler(result);
+			item = this.#items.shift();
+		}
+		this.#runners -= 1;
+	}
+};
+var QueueError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = ERROR_NAME;
+	}
+};
+function getBooleanOrDefault(value, defaultValue) {
+	return typeof value === "boolean" ? value : defaultValue;
+}
+function getNumberOrDefault(value, defaultValue) {
+	return typeof value === "number" && value > 0 ? Math.floor(value) : defaultValue;
+}
+function getOptions(input) {
+	const options = typeof input === "object" && input != null ? input : {};
+	return {
+		autostart: getBooleanOrDefault(options.autostart, true),
+		concurrency: getNumberOrDefault(options.concurrency, 1),
+		maximum: getNumberOrDefault(options.maximum, 0)
+	};
+}
+function queue(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_CALLBACK);
+	return new Queue(callback, getOptions(options));
+}
+const ERROR_NAME = "QueueError";
+const MESSAGE_CALLBACK = "A Queue requires a callback function";
+const MESSAGE_CLEAR = "Queue was cleared";
+const MESSAGE_MAXIMUM = "Queue has reached its maximum size";
+const MESSAGE_REMOVE = "Item removed from queue";
 function findKey(needle, haystack) {
 	const keys = Object.keys(haystack);
 	const index = keys.map((key) => key.toLowerCase()).indexOf(needle.toLowerCase());
@@ -2980,4 +3213,4 @@ function unsmush(value) {
 	}
 	return unsmushed;
 }
-export { frame_rate_default as FRAME_RATE_MS, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, createUuid, debounce, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, includes, indexOf, insert, isArrayOrPlainObject, isColor, isEmpty, isError, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, push, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, unique, unsmush, unwrap, upperCase, words };
+export { frame_rate_default as FRAME_RATE_MS, PromiseTimeoutError, QueueError, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, createUuid, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, includes, indexOf, insert, isArrayOrPlainObject, isColor, isEmpty, isError, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, promises, push, queue, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, unique, unsmush, unwrap, upperCase, words };

package/dist/index.js

@@ -37,6 +37,8 @@ import { SizedMap, SizedSet } from "./sized.js";
 import { debounce, memoize, throttle } from "./function.js";
 import { logger } from "./logger.js";
 import { average, count, min, round, sum } from "./math.js";
+import { PromiseTimeoutError, delay, promises, timed } from "./promise.js";
+import { QueueError, queue } from "./queue.js";
 import { setValue } from "./internal/value/set.js";
 import { fromQuery, toQuery } from "./query.js";
 import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomHex, getRandomItem, getRandomItems } from "./random.js";
@@ -54,4 +56,4 @@ import { partial } from "./value/partial.js";
 import { smush } from "./value/smush.js";
 import { unsmush } from "./value/unsmush.js";
 import "./value/index.js";
-export { frame_rate_default as FRAME_RATE_MS, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, createUuid, debounce, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, includes, indexOf, insert, isArrayOrPlainObject, isColor, isEmpty, isError, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, push, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, unique, unsmush, unwrap, upperCase, words };
+export { frame_rate_default as FRAME_RATE_MS, PromiseTimeoutError, QueueError, SizedMap, SizedSet, average, beacon, between, camelCase, capitalize, chunk, clamp, clone, compact, compare, count, createUuid, debounce, delay, diff, endsWith, equal, error, exists, filter, find, flatten, fromQuery, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, includes, indexOf, insert, isArrayOrPlainObject, isColor, isEmpty, isError, isHexColor, isHslColor, isHslLike, isHslaColor, isKey, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, memoize, merge, min, noop, ok, parse, partial, pascalCase, promises, push, queue, result, rgbToHex, rgbToHsl, rgbToHsla, round, setValue, shuffle, smush, snakeCase, sort, splice, startsWith, sum, template, throttle, timed, titleCase, toMap, toQuery, toRecord, toSet, trim, truncate, unique, unsmush, unwrap, upperCase, words };

package/dist/promise.js

@@ -0,0 +1,66 @@
+var PromiseTimeoutError = class extends Error {
+	constructor() {
+		super(MESSAGE_TIMEOUT);
+		this.name = NAME;
+	}
+};
+/**
+* Create a delayed promise that resolves after a certain amount of time
+* @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+* @returns A promise that resolves after the delay
+*/
+function delay(time) {
+	return new Promise((resolve) => setTimeout(resolve, getNumberOrDefault(time)));
+}
+function getBooleanOrDefault(value, defaultValue) {
+	return typeof value === "boolean" ? value : defaultValue;
+}
+function getNumberOrDefault(value) {
+	return typeof value === "number" ? value : 0;
+}
+async function promises(items, eager) {
+	const actual = items.filter((item) => item instanceof Promise);
+	if (actual.length === 0) return actual;
+	const isEager = getBooleanOrDefault(eager, false);
+	const { length } = actual;
+	const data = {
+		last: length - 1,
+		result: []
+	};
+	let handlers;
+	return new Promise((resolve, reject) => {
+		handlers = {
+			reject,
+			resolve
+		};
+		for (let index = 0; index < length; index += 1) actual[index].then((value) => resolveResult(index, data, handlers, value, isEager)).catch((reason) => rejectResult(index, data, handlers, reason, isEager));
+	});
+}
+function rejectResult(index, data, handlers, reason, eager) {
+	if (eager) handlers.reject(reason);
+	else {
+		data.result[index] = {
+			status: TYPE_REJECTED,
+			reason
+		};
+		if (index === data.last) handlers.resolve(data.result);
+	}
+}
+function resolveResult(index, data, handlers, value, eager) {
+	data.result[index] = eager ? value : {
+		status: TYPE_FULFILLED,
+		value
+	};
+	if (index === data.last) handlers.resolve(data.result);
+}
+function timed(promise, timeout) {
+	if (!(promise instanceof Promise)) throw new TypeError(MESSAGE_EXPECTATION);
+	if (getNumberOrDefault(timeout) <= 0) return promise;
+	return Promise.race([promise, new Promise((_, reject) => setTimeout(() => reject(new PromiseTimeoutError()), timeout))]);
+}
+var MESSAGE_EXPECTATION = "Timed function expected a Promise";
+var MESSAGE_TIMEOUT = "Promise timed out";
+var NAME = "PromiseTimeoutError";
+var TYPE_FULFILLED = "fulfilled";
+var TYPE_REJECTED = "rejected";
+export { PromiseTimeoutError, delay, promises, timed };

package/dist/queue.js

@@ -0,0 +1,169 @@
+var Queue = class {
+	#callback;
+	#handled = [];
+	#id = 0;
+	#items = [];
+	#options;
+	#paused;
+	#runners = 0;
+	/**
+	* Is the queue active?
+	*/
+	get active() {
+		return this.#runners > 0;
+	}
+	/**
+	* Is the queue empty?
+	*/
+	get empty() {
+		return this.#items.length === 0;
+	}
+	/**
+	* Is the queue full?
+	*/
+	get full() {
+		return this.#options.maximum > 0 && this.#items.length >= this.#options.maximum;
+	}
+	/**
+	* Is the queue paused?
+	*/
+	get paused() {
+		return this.#paused;
+	}
+	/**
+	* Number of items in the queue
+	*/
+	get size() {
+		return this.#items.length;
+	}
+	constructor(callback, options) {
+		this.#callback = callback;
+		this.#options = options;
+		this.#paused = !options.autostart;
+	}
+	/**
+	* Add an item to the queue
+	* @param parameters Parameters to use when item runs
+	* @returns Queued item
+	*/
+	add(...parameters) {
+		if (this.full) throw new QueueError(MESSAGE_MAXIMUM);
+		let rejector;
+		let resolver;
+		const id = this.#identify();
+		const promise = new Promise((resolve, reject) => {
+			rejector = reject;
+			resolver = resolve;
+		});
+		this.#items.push({
+			id,
+			parameters,
+			promise,
+			reject: rejector,
+			resolve: resolver
+		});
+		if (this.#options.autostart) this.#run();
+		return {
+			id,
+			promise
+		};
+	}
+	/**
+	* Remove and reject all items in the queue
+	*/
+	clear() {
+		const items = this.#items.splice(0);
+		const { length } = items;
+		for (let index = 0; index < length; index += 1) items[index].reject(new QueueError(MESSAGE_CLEAR));
+	}
+	/**
+	* Pause the queue
+	*
+	* - Currently running items will not be stopped
+	* - New added items will not run until the queue is resumed
+	*/
+	pause() {
+		this.#paused = true;
+	}
+	/**
+	* Remove and reject a specific item in the queue
+	* @param id ID of queued item
+	*/
+	remove(id) {
+		const index = this.#items.findIndex((item) => item.id === id);
+		if (index > -1) {
+			const [item] = this.#items.splice(index, 1);
+			item.reject(new QueueError(MESSAGE_REMOVE));
+		}
+	}
+	/**
+	* Resume the queue
+	*/
+	resume() {
+		if (this.#paused) {
+			const handled = this.#handled.splice(0);
+			const { length } = handled;
+			for (let index = 0; index < length; index += 1) handled[index]();
+		}
+		this.#paused = false;
+		const length = Math.min(this.#options.concurrency, this.#items.length);
+		for (let index = 0; index < length; index += 1) this.#run();
+	}
+	#identify() {
+		this.#id += 1;
+		return this.#id;
+	}
+	async #run() {
+		if (this.#paused || this.#runners >= this.#options.concurrency) return;
+		this.#runners += 1;
+		let item = this.#items.shift();
+		while (item != null) {
+			let handler;
+			let result;
+			try {
+				result = await this.#callback(...item.parameters);
+				handler = item.resolve;
+			} catch (thrown) {
+				result = thrown;
+				handler = item.reject;
+			}
+			if (this.#paused) {
+				this.#handled.push(() => handler(result));
+				break;
+			}
+			handler(result);
+			item = this.#items.shift();
+		}
+		this.#runners -= 1;
+	}
+};
+var QueueError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = ERROR_NAME;
+	}
+};
+function getBooleanOrDefault(value, defaultValue) {
+	return typeof value === "boolean" ? value : defaultValue;
+}
+function getNumberOrDefault(value, defaultValue) {
+	return typeof value === "number" && value > 0 ? Math.floor(value) : defaultValue;
+}
+function getOptions(input) {
+	const options = typeof input === "object" && input != null ? input : {};
+	return {
+		autostart: getBooleanOrDefault(options.autostart, true),
+		concurrency: getNumberOrDefault(options.concurrency, 1),
+		maximum: getNumberOrDefault(options.maximum, 0)
+	};
+}
+function queue(callback, options) {
+	if (typeof callback !== "function") throw new TypeError(MESSAGE_CALLBACK);
+	return new Queue(callback, getOptions(options));
+}
+var ERROR_NAME = "QueueError";
+var MESSAGE_CALLBACK = "A Queue requires a callback function";
+var MESSAGE_CLEAR = "Queue was cleared";
+var MESSAGE_MAXIMUM = "Queue has reached its maximum size";
+var MESSAGE_REMOVE = "Item removed from queue";
+export { QueueError, queue };

package/package.json

@@ -7,9 +7,9 @@
 	"devDependencies": {
 		"@types/node": "^25.2",
 		"@vitest/coverage-istanbul": "^4",
-		"jsdom": "^28",
-		"oxfmt": "^0.31",
-		"oxlint": "^1.46",
+		"jsdom": "^28.1",
+		"oxfmt": "^0.33",
+		"oxlint": "^1.48",
 		"rolldown": "1.0.0-rc.4",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
@@ -19,75 +19,90 @@
 	"exports": {
 		"./package.json": "./package.json",
 		".": {
-				"types": "./types/index.d.ts",
-				"default": "./dist/index.js"
+			"types": "./types/index.d.ts",
+			"default": "./dist/index.js"
 		},
 		"./array": {
-				"types": "./types/array/index.d.ts",
-				"default": "./dist/array/index.js"
+			"types": "./types/array/index.d.ts",
+			"default": "./dist/array/index.js"
 		},
 		"./beacon": {
-				"types": "./types/beacon.d.ts",
-				"default": "./dist/beacon.js"
+			"types": "./types/beacon.d.ts",
+			"default": "./dist/beacon.js"
 		},
 		"./color": {
-				"types": "./types/color/index.d.ts",
-				"default": "./dist/color/index.js"
+			"types": "./types/color/index.d.ts",
+			"default": "./dist/color/index.js"
 		},
 		"./frame-rate": {
 			"types": "./types/internal/frame-rate.d.ts",
 			"default": "./dist/internal/frame-rate.js"
 		},
 		"./function": {
-				"types": "./types/function.d.ts",
-				"default": "./dist/function.js"
+			"types": "./types/function.d.ts",
+			"default": "./dist/function.js"
 		},
 		"./is": {
-				"types": "./types/is.d.ts",
-				"default": "./dist/is.js"
+			"types": "./types/is.d.ts",
+			"default": "./dist/is.js"
 		},
 		"./logger": {
-				"types": "./types/logger.d.ts",
-				"default": "./dist/logger.js"
+			"types": "./types/logger.d.ts",
+			"default": "./dist/logger.js"
 		},
 		"./math": {
-				"types": "./types/math.d.ts",
-				"default": "./dist/math.js"
+			"types": "./types/math.d.ts",
+			"default": "./dist/math.js"
 		},
 		"./models": {
-				"types": "./types/models.d.ts"
+			"types": "./types/models.d.ts"
 		},
 		"./number": {
-				"types": "./types/number.d.ts",
-				"default": "./dist/number.js"
+			"types": "./types/number.d.ts",
+			"default": "./dist/number.js"
+		},
+		"./promise": {
+			"types": "./types/promise.d.ts",
+			"default": "./dist/promise.js"
+		},
+		"./queue": {
+			"types": "./types/queue.d.ts",
+			"default": "./dist/queue.js"
 		},
 		"./query": {
-				"types": "./types/query.d.ts",
-				"default": "./dist/query.js"
+			"types": "./types/query.d.ts",
+			"default": "./dist/query.js"
 		},
 		"./random": {
-				"types": "./types/random.d.ts",
-				"default": "./dist/random.js"
+			"types": "./types/random.d.ts",
+			"default": "./dist/random.js"
 		},
 		"./result": {
-				"types": "./types/result.d.ts",
-				"default": "./dist/result.js"
+			"types": "./types/result.d.ts",
+			"default": "./dist/result.js"
 		},
 		"./sized": {
-				"types": "./types/sized.d.ts",
-				"default": "./dist/sized.js"
+			"types": "./types/sized.d.ts",
+			"default": "./dist/sized.js"
 		},
 		"./string": {
-				"types": "./types/string/index.d.ts",
-				"default": "./dist/string/index.js"
+			"types": "./types/string/index.d.ts",
+			"default": "./dist/string/index.js"
 		},
 		"./value": {
-				"types": "./types/value/index.d.ts",
-				"default": "./dist/value/index.js"
+			"types": "./types/value/index.d.ts",
+			"default": "./dist/value/index.js"
 		}
 	},
-	"files": ["dist", "src", "types"],
-	"keywords": ["helper", "utility"],
+	"files": [
+		"dist",
+		"src",
+		"types"
+	],
+	"keywords": [
+		"helper",
+		"utility"
+	],
 	"license": "MIT",
 	"module": "./dist/index.js",
 	"name": "@oscarpalmer/atoms",
@@ -105,5 +120,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.131.0"
+	"version": "0.133.0"
 }

package/src/index.ts

@@ -9,6 +9,8 @@ export * from './logger';
 export * from './math';
 export * from './models';
 export * from './number';
+export * from './promise';
+export * from './queue';
 export * from './query';
 export * from './random';
 export * from './result';

package/src/models.ts

@@ -25,6 +25,11 @@ export type EventPosition = {
 	y: number;
 };
 
+/**
+ * A generic async callback function
+ */
+export type GenericAsyncCallback = (...args: any[]) => Promise<any>;
+
 /**
  * A generic callback function
  */

package/src/promise.ts

@@ -0,0 +1,175 @@
+// #region Types
+
+type Data<Items extends unknown[]> = {
+	last: number;
+	result: Items | PromisesResult<Items>;
+};
+
+type Handlers<Items extends unknown[]> = {
+	resolve: (value: Items | PromisesResult<Items>) => void;
+	reject: (reason: unknown) => void;
+};
+
+export class PromiseTimeoutError extends Error {
+	constructor() {
+		super(MESSAGE_TIMEOUT);
+
+		this.name = NAME;
+	}
+}
+
+type Promises<Items extends unknown[]> = {
+	[K in keyof Items]: Promise<Items[K]>;
+};
+
+type PromisesResult<Items extends unknown[]> = {
+	[K in keyof Items]: ResolvedResult<Items[K]> | RejectedResult;
+};
+
+type RejectedResult = {
+	status: typeof TYPE_REJECTED;
+	reason: unknown;
+};
+
+type ResolvedResult<Value> = {
+	status: typeof TYPE_FULFILLED;
+	value: Value;
+};
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Create a delayed promise that resolves after a certain amount of time
+ * @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+ * @returns A promise that resolves after the delay
+ */
+export function delay(time?: number): Promise<void> {
+	return new Promise(resolve => setTimeout(resolve, getNumberOrDefault(time)));
+}
+
+function getBooleanOrDefault(value: unknown, defaultValue: boolean): boolean {
+	return typeof value === 'boolean' ? value : defaultValue;
+}
+
+function getNumberOrDefault(value: unknown): number {
+	return typeof value === 'number' ? value : 0;
+}
+
+/**
+ * Handle a list of promises, returning their results in an ordered array. If any promise in the list is rejected, the whole function will reject
+ * @param items List of promises
+ * @param eager Reject immediately if any promise is rejected
+ * @return List of results
+ */
+export async function promises<Items extends unknown[]>(
+	items: Promises<Items>,
+	eager: true,
+): Promise<Items>;
+
+/**
+ * Handle a list of promises, returning their results in an ordered array of rejected and resolved results
+ * @param items List of promises
+ * @return List of results
+ */
+export async function promises<Items extends unknown[]>(
+	items: Promises<Items>,
+): Promise<PromisesResult<Items>>;
+
+export async function promises<Items extends unknown[]>(
+	items: Promises<Items>,
+	eager?: unknown,
+): Promise<Items | PromisesResult<Items>> {
+	const actual = items.filter(item => item instanceof Promise);
+
+	if (actual.length === 0) {
+		return actual as unknown as Items | PromisesResult<Items>;
+	}
+
+	const isEager = getBooleanOrDefault(eager, false);
+
+	const {length} = actual;
+
+	const data: Data<Items> = {
+		last: length - 1,
+		result: [] as unknown as Items | PromisesResult<Items>,
+	};
+
+	let handlers: Handlers<Items>;
+
+	return new Promise((resolve, reject) => {
+		handlers = {reject, resolve};
+
+		for (let index = 0; index < length; index += 1) {
+			void actual[index]
+				.then(value => resolveResult(index, data, handlers, value, isEager))
+				.catch(reason => rejectResult(index, data, handlers, reason, isEager));
+		}
+	});
+}
+
+function rejectResult<Items extends unknown[]>(
+	index: number,
+	data: Data<Items>,
+	handlers: Handlers<Items>,
+	reason: unknown,
+	eager: boolean,
+) {
+	if (eager) {
+		handlers.reject(reason);
+	} else {
+		data.result[index] = {status: TYPE_REJECTED, reason};
+
+		if (index === data.last) {
+			handlers.resolve(data.result as Items | PromisesResult<Items>);
+		}
+	}
+}
+
+function resolveResult<Items extends unknown[]>(
+	index: number,
+	data: Data<Items>,
+	handlers: Handlers<Items>,
+	value: unknown,
+	eager: boolean,
+) {
+	(data.result as unknown[])[index] = eager ? value : {status: TYPE_FULFILLED, value};
+
+	if (index === data.last) {
+		handlers.resolve(data.result as Items | PromisesResult<Items>);
+	}
+}
+
+export function timed(promise: Promise<unknown>, timeout: number): Promise<unknown> {
+	if (!(promise instanceof Promise)) {
+		throw new TypeError(MESSAGE_EXPECTATION);
+	}
+
+	const time = getNumberOrDefault(timeout);
+
+	if (time <= 0) {
+		return promise;
+	}
+
+	return Promise.race([
+		promise,
+		new Promise((_, reject) => setTimeout(() => reject(new PromiseTimeoutError()), timeout)),
+	]);
+}
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE_EXPECTATION = 'Timed function expected a Promise';
+
+const MESSAGE_TIMEOUT = 'Promise timed out';
+
+const NAME = 'PromiseTimeoutError';
+
+const TYPE_FULFILLED = 'fulfilled';
+
+const TYPE_REJECTED = 'rejected';
+
+// #endregion

package/src/queue.ts

@@ -0,0 +1,308 @@
+import type {GenericAsyncCallback, GenericCallback} from './models';
+
+// #region Types and classes
+
+class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
+	readonly #callback: GenericAsyncCallback;
+
+	readonly #handled: Array<GenericCallback> = [];
+
+	#id = 0;
+
+	readonly #items: Array<QueuedItem<CallbackParameters, CallbackResult>> = [];
+
+	readonly #options: Required<QueueOptions>;
+
+	#paused: boolean;
+
+	#runners = 0;
+
+	/**
+	 * Is the queue active?
+	 */
+	get active(): boolean {
+		return this.#runners > 0;
+	}
+
+	/**
+	 * Is the queue empty?
+	 */
+	get empty(): boolean {
+		return this.#items.length === 0;
+	}
+
+	/**
+	 * Is the queue full?
+	 */
+	get full(): boolean {
+		return this.#options.maximum > 0 && this.#items.length >= this.#options.maximum;
+	}
+
+	/**
+	 * Is the queue paused?
+	 */
+	get paused(): boolean {
+		return this.#paused;
+	}
+
+	/**
+	 * Number of items in the queue
+	 */
+	get size(): number {
+		return this.#items.length;
+	}
+
+	constructor(callback: GenericAsyncCallback, options: Required<QueueOptions>) {
+		this.#callback = callback;
+		this.#options = options;
+
+		this.#paused = !options.autostart;
+	}
+
+	/**
+	 * Add an item to the queue
+	 * @param parameters Parameters to use when item runs
+	 * @returns Queued item
+	 */
+	add(...parameters: CallbackParameters): Queued<CallbackResult> {
+		if (this.full) {
+			throw new QueueError(MESSAGE_MAXIMUM);
+		}
+
+		let rejector: (reason?: unknown) => void;
+		let resolver: (value: CallbackResult) => void;
+
+		const id = this.#identify();
+
+		const promise = new Promise<CallbackResult>((resolve, reject) => {
+			rejector = reject;
+			resolver = resolve;
+		});
+
+		this.#items.push({
+			id,
+			parameters,
+			promise,
+			reject: rejector!,
+			resolve: resolver!,
+		});
+
+		if (this.#options.autostart) {
+			void this.#run();
+		}
+
+		return {id, promise};
+	}
+
+	/**
+	 * Remove and reject all items in the queue
+	 */
+	clear(): void {
+		const items = this.#items.splice(0);
+		const {length} = items;
+
+		for (let index = 0; index < length; index += 1) {
+			items[index].reject(new QueueError(MESSAGE_CLEAR));
+		}
+	}
+
+	/**
+	 * Pause the queue
+	 *
+	 * - Currently running items will not be stopped
+	 * - New added items will not run until the queue is resumed
+	 */
+	pause(): void {
+		this.#paused = true;
+	}
+
+	/**
+	 * Remove and reject a specific item in the queue
+	 * @param id ID of queued item
+	 */
+	remove(id: number): void {
+		const index = this.#items.findIndex(item => item.id === id);
+
+		if (index > -1) {
+			const [item] = this.#items.splice(index, 1);
+
+			item.reject(new QueueError(MESSAGE_REMOVE));
+		}
+	}
+
+	/**
+	 * Resume the queue
+	 */
+	resume(): void {
+		if (this.#paused) {
+			const handled = this.#handled.splice(0);
+			const {length} = handled;
+
+			for (let index = 0; index < length; index += 1) {
+				handled[index]();
+			}
+		}
+
+		this.#paused = false;
+
+		const length = Math.min(this.#options.concurrency, this.#items.length);
+
+		for (let index = 0; index < length; index += 1) {
+			void this.#run();
+		}
+	}
+
+	#identify(): number {
+		this.#id += 1;
+
+		return this.#id;
+	}
+
+	async #run(): Promise<void> {
+		if (this.#paused || this.#runners >= this.#options.concurrency) {
+			return;
+		}
+
+		this.#runners += 1;
+
+		let item = this.#items.shift();
+
+		while (item != null) {
+			let handler: GenericCallback;
+			let result: unknown | CallbackResult;
+
+			try {
+				result = await this.#callback(...item.parameters);
+				handler = item.resolve;
+			} catch (thrown) {
+				result = thrown;
+				handler = item.reject;
+			}
+
+			if (this.#paused) {
+				this.#handled.push(() => handler(result));
+
+				break;
+			}
+
+			handler(result);
+
+			item = this.#items.shift();
+		}
+
+		this.#runners -= 1;
+	}
+}
+
+class QueueError extends Error {
+	constructor(message: string) {
+		super(message);
+
+		this.name = ERROR_NAME;
+	}
+}
+
+type QueueOptions = {
+	/**
+	 * Automatically start processing the queue when the first item is added _(defaults to `true`)_
+	 */
+	autostart?: boolean;
+	/**
+	 * Number of runners to process the queue concurrently _(defaults to `1`)_
+	 */
+	concurrency?: number;
+	/**
+	 * Maximum number of items allowed in the queue _(defaults to `0`, which means no limit)_
+	 */
+	maximum?: number;
+};
+
+type Queued<Value> = {
+	readonly id: number;
+	readonly promise: Promise<Value>;
+};
+
+type QueuedItem<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> = {
+	id: number;
+	parameters: CallbackParameters;
+	promise: Promise<CallbackResult>;
+	reject: (reason?: unknown) => void;
+	resolve: (value: CallbackResult) => void;
+};
+
+// #endregion
+
+// #region Functions
+
+function getBooleanOrDefault(value: unknown, defaultValue: boolean): boolean {
+	return typeof value === 'boolean' ? value : defaultValue;
+}
+
+function getNumberOrDefault(value: unknown, defaultValue: number): number {
+	return typeof value === 'number' && value > 0 ? Math.floor(value) : defaultValue;
+}
+
+function getOptions(input?: QueueOptions): Required<QueueOptions> {
+	const options = typeof input === 'object' && input != null ? input : {};
+
+	return {
+		autostart: getBooleanOrDefault(options.autostart, true),
+		concurrency: getNumberOrDefault(options.concurrency, 1),
+		maximum: getNumberOrDefault(options.maximum, 0),
+	};
+}
+
+/**
+ * Create a queue for an asynchronous callback function
+ * @param callback Callback function for queued items
+ * @param options Queue options
+ * @returns Queue instance
+ */
+function queue<Callback extends GenericAsyncCallback>(
+	callback: Callback,
+	options?: QueueOptions,
+): Queue<Parameters<Callback>, Awaited<ReturnType<Callback>>>;
+
+/**
+ * Create a queue for an asynchronous callback function
+ * @param callback Callback function for queued items
+ * @param options Queue options
+ * @returns Queue instance
+ */
+function queue<Callback extends GenericCallback>(
+	callback: Callback,
+	options?: QueueOptions,
+): Queue<Parameters<Callback>, ReturnType<Callback>>;
+
+function queue(
+	callback: GenericCallback,
+	options?: QueueOptions,
+): Queue<Parameters<GenericCallback>, ReturnType<GenericCallback>> {
+	if (typeof callback !== 'function') {
+		throw new TypeError(MESSAGE_CALLBACK);
+	}
+
+	return new Queue(callback, getOptions(options));
+}
+
+// #endregion
+
+// #region Variables
+
+const ERROR_NAME = 'QueueError';
+
+const MESSAGE_CALLBACK = 'A Queue requires a callback function';
+
+const MESSAGE_CLEAR = 'Queue was cleared';
+
+const MESSAGE_MAXIMUM = 'Queue has reached its maximum size';
+
+const MESSAGE_REMOVE = 'Item removed from queue';
+
+// #endregion
+
+// #region Exports
+
+export {queue, QueueError, type Queue, type Queued, type QueueOptions};
+
+// #endregion

package/types/index.d.ts

@@ -8,6 +8,8 @@ export * from './logger';
 export * from './math';
 export * from './models';
 export * from './number';
+export * from './promise';
+export * from './queue';
 export * from './query';
 export * from './random';
 export * from './result';

package/types/models.d.ts

@@ -19,6 +19,10 @@ export type EventPosition = {
     x: number;
     y: number;
 };
+/**
+ * A generic async callback function
+ */
+export type GenericAsyncCallback = (...args: any[]) => Promise<any>;
 /**
  * A generic callback function
  */

package/types/promise.d.ts

@@ -0,0 +1,40 @@
+export declare class PromiseTimeoutError extends Error {
+    constructor();
+}
+type Promises<Items extends unknown[]> = {
+    [K in keyof Items]: Promise<Items[K]>;
+};
+type PromisesResult<Items extends unknown[]> = {
+    [K in keyof Items]: ResolvedResult<Items[K]> | RejectedResult;
+};
+type RejectedResult = {
+    status: typeof TYPE_REJECTED;
+    reason: unknown;
+};
+type ResolvedResult<Value> = {
+    status: typeof TYPE_FULFILLED;
+    value: Value;
+};
+/**
+ * Create a delayed promise that resolves after a certain amount of time
+ * @param time How long to wait for _(in milliseconds; defaults to screen refresh rate)_
+ * @returns A promise that resolves after the delay
+ */
+export declare function delay(time?: number): Promise<void>;
+/**
+ * Handle a list of promises, returning their results in an ordered array. If any promise in the list is rejected, the whole function will reject
+ * @param items List of promises
+ * @param eager Reject immediately if any promise is rejected
+ * @return List of results
+ */
+export declare function promises<Items extends unknown[]>(items: Promises<Items>, eager: true): Promise<Items>;
+/**
+ * Handle a list of promises, returning their results in an ordered array of rejected and resolved results
+ * @param items List of promises
+ * @return List of results
+ */
+export declare function promises<Items extends unknown[]>(items: Promises<Items>): Promise<PromisesResult<Items>>;
+export declare function timed(promise: Promise<unknown>, timeout: number): Promise<unknown>;
+declare const TYPE_FULFILLED = "fulfilled";
+declare const TYPE_REJECTED = "rejected";
+export {};

package/types/queue.d.ts

@@ -0,0 +1,87 @@
+import type { GenericAsyncCallback, GenericCallback } from './models';
+declare class Queue<CallbackParameters extends Parameters<GenericAsyncCallback>, CallbackResult> {
+    #private;
+    /**
+     * Is the queue active?
+     */
+    get active(): boolean;
+    /**
+     * Is the queue empty?
+     */
+    get empty(): boolean;
+    /**
+     * Is the queue full?
+     */
+    get full(): boolean;
+    /**
+     * Is the queue paused?
+     */
+    get paused(): boolean;
+    /**
+     * Number of items in the queue
+     */
+    get size(): number;
+    constructor(callback: GenericAsyncCallback, options: Required<QueueOptions>);
+    /**
+     * Add an item to the queue
+     * @param parameters Parameters to use when item runs
+     * @returns Queued item
+     */
+    add(...parameters: CallbackParameters): Queued<CallbackResult>;
+    /**
+     * Remove and reject all items in the queue
+     */
+    clear(): void;
+    /**
+     * Pause the queue
+     *
+     * - Currently running items will not be stopped
+     * - New added items will not run until the queue is resumed
+     */
+    pause(): void;
+    /**
+     * Remove and reject a specific item in the queue
+     * @param id ID of queued item
+     */
+    remove(id: number): void;
+    /**
+     * Resume the queue
+     */
+    resume(): void;
+}
+declare class QueueError extends Error {
+    constructor(message: string);
+}
+type QueueOptions = {
+    /**
+     * Automatically start processing the queue when the first item is added _(defaults to `true`)_
+     */
+    autostart?: boolean;
+    /**
+     * Number of runners to process the queue concurrently _(defaults to `1`)_
+     */
+    concurrency?: number;
+    /**
+     * Maximum number of items allowed in the queue _(defaults to `0`, which means no limit)_
+     */
+    maximum?: number;
+};
+type Queued<Value> = {
+    readonly id: number;
+    readonly promise: Promise<Value>;
+};
+/**
+ * Create a queue for an asynchronous callback function
+ * @param callback Callback function for queued items
+ * @param options Queue options
+ * @returns Queue instance
+ */
+declare function queue<Callback extends GenericAsyncCallback>(callback: Callback, options?: QueueOptions): Queue<Parameters<Callback>, Awaited<ReturnType<Callback>>>;
+/**
+ * Create a queue for an asynchronous callback function
+ * @param callback Callback function for queued items
+ * @param options Queue options
+ * @returns Queue instance
+ */
+declare function queue<Callback extends GenericCallback>(callback: Callback, options?: QueueOptions): Queue<Parameters<Callback>, ReturnType<Callback>>;
+export { queue, QueueError, type Queue, type Queued, type QueueOptions };