@oscarpalmer/atoms 0.157.0 → 0.158.0

package/dist/atoms.full.js

@@ -244,12 +244,12 @@ function findValues(type, array, parameters, mapper) {
 	const { length } = array;
 	const { bool, key, value } = getParameters(parameters);
 	const callbacks = getArrayCallbacks(bool, key);
-	if (type === FIND_VALUES_UNIQUE && callbacks?.keyed == null && length >= UNIQUE_THRESHOLD) {
+	if (type === "unique" && callbacks?.keyed == null && length >= UNIQUE_THRESHOLD) {
 		result.matched = [...new Set(array)];
 		return result;
 	}
 	const mapCallback = typeof mapper === "function" ? mapper : void 0;
-	if (callbacks?.bool != null || type === FIND_VALUES_ALL && key == null) {
+	if (callbacks?.bool != null || type === "all" && key == null) {
 		const callback = callbacks?.bool ?? ((item) => Object.is(item, value));
 		for (let index = 0; index < length; index += 1) {
 			const item = array[index];
@@ -262,7 +262,7 @@ function findValues(type, array, parameters, mapper) {
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
 		const keyed = callbacks?.keyed?.(item, index, array) ?? item;
-		if (type === FIND_VALUES_ALL && Object.is(keyed, value) || type === FIND_VALUES_UNIQUE && !keys.has(keyed)) {
+		if (type === "all" && Object.is(keyed, value) || type === "unique" && !keys.has(keyed)) {
 			keys.add(keyed);
 			result.matched.push(mapCallback?.(item, index, array) ?? item);
 		} else result.notMatched.push(item);
@@ -279,7 +279,6 @@ function getParameters(original) {
 }
 const FIND_VALUE_INDEX = "index";
 const FIND_VALUE_VALUE = "value";
-const FIND_VALUES_ALL = "all";
 const FIND_VALUES_UNIQUE = "unique";
 const UNIQUE_THRESHOLD = 100;
 function exists(array, ...parameters) {
@@ -287,11 +286,11 @@ function exists(array, ...parameters) {
 	return findValue(FIND_VALUE_INDEX, array, parameters) > -1;
 }
 function filter(array, ...parameters) {
-	return findValues(FIND_VALUES_ALL, array, parameters).matched;
+	return findValues("all", array, parameters).matched;
 }
 filter.remove = removeFiltered;
 function removeFiltered(array, ...parameters) {
-	return findValues(FIND_VALUES_ALL, array, parameters).notMatched;
+	return findValues("all", array, parameters).notMatched;
 }
 function find(array, ...parameters) {
 	return findValue(FIND_VALUE_VALUE, array, parameters);
@@ -366,7 +365,7 @@ function intersection(first, second, key) {
 	return compareSets(COMPARE_SETS_INTERSECTION, first, second, key);
 }
 function partition(array, ...parameters) {
-	const { matched, notMatched } = findValues(FIND_VALUES_ALL, array, parameters);
+	const { matched, notMatched } = findValues("all", array, parameters);
 	return [matched, notMatched];
 }
 /**
@@ -379,7 +378,7 @@ function push(array, pushed) {
 	return insertValues("push", array, pushed, array.length, 0);
 }
 function select(array, ...parameters) {
-	return findValues(FIND_VALUES_ALL, array, parameters, parameters.pop()).matched;
+	return findValues("all", array, parameters, parameters.pop()).matched;
 }
 function drop(array, first, second) {
 	return extract(EXTRACT_DROP, array, first, second);
@@ -1017,6 +1016,159 @@ function memoize(callback, options) {
 }
 const DEFAULT_CACHE_SIZE = 1024;
 /**
+* Asserts that a condition is true, throwing an error if it is not
+* @param condition Condition to assert
+* @param message Error message
+* @param error Error constructor
+*/
+function assert(condition, message, error) {
+	if (!condition()) throw new (error ?? Error)(message);
+}
+assert.condition = assertCondition;
+assert.defined = assertDefined;
+assert.instanceOf = assertInstanceOf;
+assert.is = assertIs;
+/**
+* Creates an asserter that asserts a condition is true, throwing an error if it is not
+* @param condition Condition to assert
+* @param message Error message
+* @param error Error constructor
+* @returns Asserter
+*/
+function assertCondition(condition, message, error) {
+	return (value) => {
+		assert(() => condition(value), message, error);
+	};
+}
+/**
+* Asserts that a value is defined throwing an error if it is not
+* @param value Value to assert
+* @param message Error message
+*/
+function assertDefined(value, message) {
+	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED);
+}
+/**
+* Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
+* @param constructor Constructor to check against
+* @param message Error message
+* @param error Error constructor
+* @returns Asserter
+*/
+function assertInstanceOf(constructor, message, error) {
+	return (value) => {
+		assert(() => value instanceof constructor, message, error);
+	};
+}
+/**
+* Creates an asserter that asserts a value is of a specific type, throwing an error if it is not
+* @param condition Type guard function to check the value
+* @param message Error message
+* @param error Error constructor
+* @returns Asserter
+*/
+function assertIs(condition, message, error) {
+	return (value) => {
+		assert(() => condition(value), message, error);
+	};
+}
+const MESSAGE_VALUE_DEFINED = "Expected value to be defined";
+/**
+* Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+* @param callback Callback to use once
+* @returns Once callback
+*/
+function asyncOnce(callback) {
+	assert(() => typeof callback === "function", MESSAGE_EXPECTATION$1);
+	const state = {
+		called: false,
+		cleared: false,
+		error: false,
+		finished: false,
+		items: [],
+		value: void 0
+	};
+	const fn = (...parameters) => {
+		if (state.cleared) return Promise.reject(new Error(MESSAGE_CLEARED));
+		if (state.finished) return state.error ? Promise.reject(state.value) : Promise.resolve(state.value);
+		if (state.called) return new Promise((resolve, reject) => {
+			state.items.push({
+				reject,
+				resolve
+			});
+		});
+		state.called = true;
+		return new Promise((resolve, reject) => {
+			state.items.push({
+				reject,
+				resolve
+			});
+			callback(...parameters).then((value) => {
+				handleResult$1(state, value, false);
+			}).catch((error) => {
+				handleResult$1(state, error, true);
+			});
+		});
+	};
+	Object.defineProperties(fn, {
+		called: { get: () => state.called },
+		cleared: { get: () => state.cleared },
+		error: { get: () => state.error },
+		finished: { get: () => state.finished }
+	});
+	fn.clear = () => {
+		if (!state.called || !state.finished || state.cleared) return;
+		state.cleared = true;
+		state.value = void 0;
+	};
+	return fn;
+}
+function handleResult$1(state, value, error) {
+	state.error = error;
+	state.finished = true;
+	state.value = value;
+	const items = state.items.splice(0);
+	const { length } = items;
+	for (let index = 0; index < length; index += 1) {
+		const { reject, resolve } = items[index];
+		if (error) reject(value);
+		else resolve(value);
+	}
+}
+/**
+* Create a function that can only be called once, returning the same value on subsequent calls
+* @param callback Callback to use once
+* @returns Once callback
+*/
+function once(callback) {
+	assert(() => typeof callback === "function", MESSAGE_EXPECTATION$1);
+	const state = {
+		called: false,
+		cleared: false,
+		value: void 0
+	};
+	const fn = (...parameters) => {
+		if (state.cleared) throw new Error(MESSAGE_CLEARED);
+		if (state.called) return state.value;
+		state.called = true;
+		state.value = callback(...parameters);
+		return state.value;
+	};
+	Object.defineProperties(fn, {
+		called: { get: () => state.called },
+		cleared: { get: () => state.cleared }
+	});
+	fn.clear = () => {
+		if (!state.called || state.cleared) return;
+		state.cleared = true;
+		state.value = void 0;
+	};
+	return fn;
+}
+once.async = asyncOnce;
+const MESSAGE_CLEARED = "Once has been cleared";
+const MESSAGE_EXPECTATION$1 = "Once expected a function";
+/**
 * Debounce a function, ensuring it is only called after `time` milliseconds have passed
 *
 * On subsequent calls, the timer is reset and will wait another `time` milliseconds _(and so on...)_
@@ -1135,64 +1287,6 @@ function isOk(value) {
 function isResult(value) {
 	return _isResult(value, true) || _isResult(value, false);
 }
-/**
-* Asserts that a condition is true, throwing an error if it is not
-* @param condition Condition to assert
-* @param message Error message
-* @param error Error constructor
-*/
-function assert(condition, message, error) {
-	if (!condition()) throw new (error ?? Error)(message);
-}
-assert.condition = assertCondition;
-assert.defined = assertDefined;
-assert.instanceOf = assertInstanceOf;
-assert.is = assertIs;
-/**
-* Creates an asserter that asserts a condition is true, throwing an error if it is not
-* @param condition Condition to assert
-* @param message Error message
-* @param error Error constructor
-* @returns Asserter
-*/
-function assertCondition(condition, message, error) {
-	return (value) => {
-		assert(() => condition(value), message, error);
-	};
-}
-/**
-* Asserts that a value is defined throwing an error if it is not
-* @param value Value to assert
-* @param message Error message
-*/
-function assertDefined(value, message) {
-	assert(() => value != null, message ?? MESSAGE_VALUE_DEFINED);
-}
-/**
-* Creates an asserter that asserts a value is an instance of a constructor, throwing an error if it is not
-* @param constructor Constructor to check against
-* @param message Error message
-* @param error Error constructor
-* @returns Asserter
-*/
-function assertInstanceOf(constructor, message, error) {
-	return (value) => {
-		assert(() => value instanceof constructor, message, error);
-	};
-}
-/**
-* Creates an asserter that asserts a value is of a specific type, throwing an error if it is not
-* @param condition Type guard function to check the value
-* @param message Error message
-* @param error Error constructor
-* @returns Asserter
-*/
-function assertIs(condition, message, error) {
-	return (value) => {
-		assert(() => condition(value), message, error);
-	};
-}
-const MESSAGE_VALUE_DEFINED = "Expected value to be defined";
 function asyncFlow(...fns) {
 	assertFlowFunctions(fns);
 	return (...args) => asyncWork(args.map((value) => {
@@ -2288,14 +2382,10 @@ function getObserver(first, second, third) {
 }
 const MESSAGE_BEACON = "Cannot retrieve observable from a destroyed beacon";
 const MESSAGE_OBSERVABLE = "Cannot subscribe to a destroyed observable";
-const ALPHA_FULL_HEX_SHORT = "f";
-const ALPHA_FULL_HEX_LONG = `${ALPHA_FULL_HEX_SHORT}${ALPHA_FULL_HEX_SHORT}`;
-const ALPHA_FULL_VALUE = 1;
-const ALPHA_NONE_HEX = "00";
-const ALPHA_NONE_VALUE = 0;
+const ALPHA_FULL_HEX_LONG = `ff`;
 const DEFAULT_ALPHA = {
 	hex: ALPHA_FULL_HEX_LONG,
-	value: ALPHA_FULL_VALUE
+	value: 1
 };
 const DEFAULT_HSL = {
 	hue: 0,
@@ -2312,8 +2402,6 @@ const EXPRESSION_HEX_SHORT = /^#?([a-f0-9]{3,4})$/i;
 const EXPRESSION_PREFIX = /^#/;
 const HEX_BLACK = "000000";
 const HEX_WHITE = "ffffff";
-const LENGTH_LONG = 6;
-const LENGTH_SHORT = 3;
 const KEYS_HSL = [
 	"hue",
 	"saturation",
@@ -2326,18 +2414,10 @@ const KEYS_RGB = [
 	"blue"
 ];
 const KEYS_RGBA = [...KEYS_RGB, "alpha"];
-const MAX_DEGREE = 360;
-const MAX_HEX = 255;
-const MAX_PERCENT = 100;
-const SRGB_LUMINANCE_BLUE = .0722;
 const SRGB_LUMINANCE_EXPONENT = 2.4;
-const SRGB_LUMINANCE_GREEN = .7152;
-const SRGB_LUMINANCE_MINIMUM = .03928;
 const SRGB_LUMINANCE_MODIFIER = 1.055;
 const SRGB_LUMINANCE_MULTIPLIER = 12.92;
 const SRGB_LUMINANCE_OFFSET = .055;
-const SRGB_LUMINANCE_RED = .2126;
-const SRGB_LUMINANCE_THRESHOLD = .625;
 function formatColor(space, color, alpha) {
 	const suffix = alpha ? ` / ${color.alpha}` : "";
 	const value = color[space];
@@ -2351,14 +2431,14 @@ function getAlpha(value) {
 	if (typeof value === "number") return getAlphaFromValue(value);
 	if (typeof value === "string" && value !== ALPHA_FULL_HEX_LONG) return {
 		hex: value,
-		value: Number.parseInt(value, 16) / MAX_HEX
+		value: Number.parseInt(value, 16) / 255
 	};
 	return { ...DEFAULT_ALPHA };
 }
 function getAlphaHexadecimal(value) {
-	if (value === ALPHA_NONE_VALUE) return ALPHA_NONE_HEX;
-	if (value === ALPHA_FULL_VALUE) return ALPHA_FULL_HEX_LONG;
-	return Math.round(value * MAX_HEX).toString(16);
+	if (value === 0) return "00";
+	if (value === 1) return ALPHA_FULL_HEX_LONG;
+	return Math.round(value * 255).toString(16);
 }
 function getAlphaFromValue(value) {
 	const alpha = getAlphaValue(value);
@@ -2368,18 +2448,18 @@ function getAlphaFromValue(value) {
 	};
 }
 function getAlphaValue(original) {
-	if (Number.isNaN(original) || original >= MAX_PERCENT || original === ALPHA_FULL_VALUE) return ALPHA_FULL_VALUE;
-	if (original < ALPHA_NONE_VALUE) return ALPHA_NONE_VALUE;
-	return original <= ALPHA_FULL_VALUE ? original : original / MAX_PERCENT;
+	if (Number.isNaN(original) || original >= 100 || original === 1) return 1;
+	if (original < 0) return 0;
+	return original <= 1 ? original : original / 100;
 }
 function hasKeys(value, keys) {
 	return typeof value === "object" && value !== null && keys.every((key) => key in value);
 }
 function isAlpha(value) {
-	return typeof value === "number" && between(value, ALPHA_NONE_VALUE, ALPHA_FULL_VALUE);
+	return typeof value === "number" && between(value, 0, 1);
 }
 function isBytey(value) {
-	return typeof value === "number" && between(value, 0, MAX_HEX);
+	return typeof value === "number" && between(value, 0, 255);
 }
 /**
 * Is the value a Color?
@@ -2401,7 +2481,7 @@ function isColorValue(obj, properties) {
 	return true;
 }
 function isDegree(value) {
-	return typeof value === "number" && between(value, 0, MAX_DEGREE);
+	return typeof value === "number" && between(value, 0, 360);
 }
 /**
 * Is the value a hex color?
@@ -2412,7 +2492,7 @@ function isDegree(value) {
 function isHexColor(value, alpha) {
 	if (typeof value !== "string") return false;
 	if (!(EXPRESSION_HEX_SHORT.test(value) || EXPRESSION_HEX_LONG.test(value))) return false;
-	if (alpha === false) return value.length === LENGTH_SHORT || value.length === LENGTH_LONG;
+	if (alpha === false) return value.length === 3 || value.length === 6;
 	return true;
 }
 /**
@@ -2454,7 +2534,7 @@ function isRgbLike(value) {
 	return hasKeys(value, KEYS_RGB);
 }
 function isPercentage(value) {
-	return typeof value === "number" && between(value, 0, MAX_PERCENT);
+	return typeof value === "number" && between(value, 0, 100);
 }
 const validators = {
 	alpha: isAlpha,
@@ -2476,17 +2556,17 @@ function getClampedValue(value, minimum, maximum) {
 function getForegroundColor(value) {
 	const { blue, green, red } = getState(value).rgb;
 	const values = [
-		blue / MAX_HEX,
-		green / MAX_HEX,
-		red / MAX_HEX
+		blue / 255,
+		green / 255,
+		red / 255
 	];
 	const { length } = values;
 	for (let index = 0; index < length; index += 1) {
 		const color = values[index];
-		if (color <= SRGB_LUMINANCE_MINIMUM) values[index] /= SRGB_LUMINANCE_MULTIPLIER;
+		if (color <= .03928) values[index] /= SRGB_LUMINANCE_MULTIPLIER;
 		else values[index] = ((color + SRGB_LUMINANCE_OFFSET) / SRGB_LUMINANCE_MODIFIER) ** SRGB_LUMINANCE_EXPONENT;
 	}
-	return new Color(SRGB_LUMINANCE_RED * values[2] + SRGB_LUMINANCE_GREEN * values[1] + SRGB_LUMINANCE_BLUE * values[0] > SRGB_LUMINANCE_THRESHOLD ? HEX_BLACK : HEX_WHITE);
+	return new Color(.2126 * values[2] + .7152 * values[1] + .0722 * values[0] > .625 ? HEX_BLACK : HEX_WHITE);
 }
 /**
 * Get the hex color _(with alpha channel)_ from any kind of value
@@ -2506,10 +2586,10 @@ function getHexColor(value) {
 	return getState(value).hex;
 }
 function getHexValue(value) {
-	return getClampedValue(value, 0, MAX_HEX);
+	return getClampedValue(value, 0, 255);
 }
 function getDegrees(value) {
-	return getClampedValue(value, 0, MAX_DEGREE);
+	return getClampedValue(value, 0, 360);
 }
 /**
 * Get the HSLA color from any kind of value
@@ -2532,7 +2612,7 @@ function getHslColor(value) {
 	return getState(value).hsl;
 }
 function getPercentage(value) {
-	return getClampedValue(value, 0, MAX_PERCENT);
+	return getClampedValue(value, 0, 100);
 }
 /**
 * Get the RGBA color from any kind of value
@@ -2569,9 +2649,9 @@ function convertRgbToHex(rgb, alpha) {
 }
 function convertRgbToHsla(value) {
 	const rgb = isRgbLike(value) ? getRgbValue(value) : { ...DEFAULT_RGB };
-	const blue = rgb.blue / MAX_HEX;
-	const green = rgb.green / MAX_HEX;
-	const red = rgb.red / MAX_HEX;
+	const blue = rgb.blue / 255;
+	const green = rgb.green / 255;
+	const red = rgb.red / 255;
 	const maxHex = Math.max(blue, green, red);
 	const minHex = Math.min(blue, green, red);
 	const delta = maxHex - minHex;
@@ -2594,10 +2674,10 @@ function convertRgbToHsla(value) {
 		hue *= 60;
 	}
 	return {
-		alpha: getAlphaValue(value.alpha ?? ALPHA_FULL_VALUE),
+		alpha: getAlphaValue(value.alpha ?? 1),
 		hue: +hue.toFixed(2),
-		lightness: +(lightness * MAX_PERCENT).toFixed(2),
-		saturation: +(saturation * MAX_PERCENT).toFixed(2)
+		lightness: +(lightness * 100).toFixed(2),
+		saturation: +(saturation * 100).toFixed(2)
 	};
 }
 function getRgbValue(value) {
@@ -2648,7 +2728,7 @@ function convertHexToRgba(value) {
 	const { length } = pairs;
 	for (let index = 1; index < length; index += 1) values.push(Number.parseInt(pairs[index], 16));
 	return {
-		alpha: values[3] / MAX_HEX,
+		alpha: values[3] / 255,
 		blue: values[2],
 		green: values[1],
 		red: values[0]
@@ -2664,8 +2744,8 @@ function getNormalizedHex(value, alpha) {
 	const includeAlpha = alpha ?? false;
 	if (!isHexColor(value)) return `${HEX_BLACK}${includeAlpha ? ALPHA_FULL_HEX_LONG : ""}`;
 	const normalized = value.replace(EXPRESSION_PREFIX, "");
-	if (normalized.length < LENGTH_LONG) return join(`${normalized.slice(0, LENGTH_SHORT)}${includeAlpha ? normalized[LENGTH_SHORT] ?? ALPHA_FULL_HEX_SHORT : ""}`.split("").map((character) => character.repeat(2)));
-	return `${normalized.slice(0, LENGTH_LONG)}${includeAlpha ? normalized.slice(LENGTH_LONG) || ALPHA_FULL_HEX_LONG : ""}`;
+	if (normalized.length < 6) return join(`${normalized.slice(0, 3)}${includeAlpha ? normalized[3] ?? "f" : ""}`.split("").map((character) => character.repeat(2)));
+	return `${normalized.slice(0, 6)}${includeAlpha ? normalized.slice(6) || ALPHA_FULL_HEX_LONG : ""}`;
 }
 function hexToHsl(value) {
 	const { hue, lightness, saturation } = hexToHsla(value);
@@ -2701,11 +2781,11 @@ function hexToRgba(value) {
 }
 function convertHslToRgba(value) {
 	const hsl = isHslLike(value) ? getHslValue(value) : { ...DEFAULT_HSL };
-	const hue = hsl.hue % MAX_DEGREE;
-	const saturation = hsl.saturation / MAX_PERCENT;
-	const lightness = hsl.lightness / MAX_PERCENT;
+	const hue = hsl.hue % 360;
+	const saturation = hsl.saturation / 100;
+	const lightness = hsl.lightness / 100;
 	return {
-		alpha: getAlphaValue(value.alpha ?? ALPHA_FULL_VALUE),
+		alpha: getAlphaValue(value.alpha ?? 1),
 		blue: getHexValue(Math.round(getHexyValue(hue, lightness, saturation, 4))),
 		green: getHexValue(Math.round(getHexyValue(hue, lightness, saturation, 8))),
 		red: getHexValue(Math.round(getHexyValue(hue, lightness, saturation, 0)))
@@ -2713,7 +2793,7 @@ function convertHslToRgba(value) {
 }
 function getHexyValue(hue, lightness, saturation, value) {
 	const part = (value + hue / 30) % 12;
-	return (lightness - saturation * Math.min(lightness, 1 - lightness) * Math.max(-1, Math.min(part - 3, 9 - part, 1))) * MAX_HEX;
+	return (lightness - saturation * Math.min(lightness, 1 - lightness) * Math.max(-1, Math.min(part - 3, 9 - part, 1))) * 255;
 }
 function getHslValue(value) {
 	return {
@@ -2753,12 +2833,12 @@ function hslToRgba(hsl) {
 function getState(value) {
 	if (typeof value === "string") {
 		const normalized = getNormalizedHex(value, true);
-		const hex = normalized.slice(0, LENGTH_LONG);
+		const hex = normalized.slice(0, 6);
 		const rgb = hexToRgb(hex);
 		return {
 			hex,
 			rgb,
-			alpha: getAlpha(normalized.slice(LENGTH_LONG)),
+			alpha: getAlpha(normalized.slice(6)),
 			hsl: rgbToHsl(rgb)
 		};
 	}
@@ -2784,7 +2864,7 @@ function getState(value) {
 			return state;
 		}
 	}
-	state.alpha ??= getAlpha(ALPHA_FULL_VALUE);
+	state.alpha ??= getAlpha(1);
 	state.hex ??= String(HEX_BLACK);
 	state.hsl ??= { ...DEFAULT_HSL };
 	state.rgb ??= { ...DEFAULT_RGB };
@@ -2793,12 +2873,12 @@ function getState(value) {
 function setHexColor(state, value, alpha) {
 	if (!isHexColor(value) || !alpha && value === state.hex) return;
 	const normalized = getNormalizedHex(value, true);
-	const hex = normalized.slice(0, LENGTH_LONG);
+	const hex = normalized.slice(0, 6);
 	const rgb = hexToRgb(hex);
 	state.hex = hex;
 	state.hsl = rgbToHsl(rgb);
 	state.rgb = rgb;
-	if (alpha) state.alpha = getAlpha(normalized.slice(LENGTH_LONG));
+	if (alpha) state.alpha = getAlpha(normalized.slice(6));
 }
 function setHSLColor(state, value, alpha) {
 	if (!isHslLike(value)) return;
@@ -3329,11 +3409,11 @@ function cancelable(executor) {
 function handleResult(status, parameters) {
 	const { abort, complete, data, handlers, index, signal, value } = parameters;
 	if (signal?.aborted ?? false) return;
-	if (!complete && status === PROMISE_TYPE_REJECTED) {
+	if (!complete && status === "rejected") {
 		settlePromise(abort, handlers.reject, value, signal);
 		return;
 	}
-	data.result[index] = !complete ? value : status === PROMISE_TYPE_FULFILLED ? {
+	data.result[index] = !complete ? value : status === "fulfilled" ? {
 		status,
 		value
 	} : {
@@ -3923,4 +4003,4 @@ var SizedSet = class extends Set {
 		}
 	}
 };
-export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, toResult, fromQuery, toPromise as fromResult, toPromise, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, sum, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, toResult, fromQuery, toPromise as fromResult, toPromise, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, sum, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/function/index.js

@@ -1,6 +1,7 @@
 import { noop } from "../internal/function/misc.js";
 import { TIMER_DEBOUNCE, TIMER_THROTTLE, getTimer } from "../internal/function/timer.js";
 import { memoize } from "./memoize.js";
+import { once } from "./once.js";
 /**
 * Debounce a function, ensuring it is only called after `time` milliseconds have passed
 *
@@ -21,4 +22,4 @@ function debounce(callback, time) {
 function throttle(callback, time) {
 	return getTimer(TIMER_THROTTLE, callback, time);
 }
-export { debounce, memoize, noop, throttle };
+export { debounce, memoize, noop, once, throttle };

package/dist/function/once.js

@@ -0,0 +1,97 @@
+import { assert } from "./assert.js";
+/**
+* Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+* @param callback Callback to use once
+* @returns Once callback
+*/
+function asyncOnce(callback) {
+	assert(() => typeof callback === "function", MESSAGE_EXPECTATION);
+	const state = {
+		called: false,
+		cleared: false,
+		error: false,
+		finished: false,
+		items: [],
+		value: void 0
+	};
+	const fn = (...parameters) => {
+		if (state.cleared) return Promise.reject(new Error(MESSAGE_CLEARED));
+		if (state.finished) return state.error ? Promise.reject(state.value) : Promise.resolve(state.value);
+		if (state.called) return new Promise((resolve, reject) => {
+			state.items.push({
+				reject,
+				resolve
+			});
+		});
+		state.called = true;
+		return new Promise((resolve, reject) => {
+			state.items.push({
+				reject,
+				resolve
+			});
+			callback(...parameters).then((value) => {
+				handleResult(state, value, false);
+			}).catch((error) => {
+				handleResult(state, error, true);
+			});
+		});
+	};
+	Object.defineProperties(fn, {
+		called: { get: () => state.called },
+		cleared: { get: () => state.cleared },
+		error: { get: () => state.error },
+		finished: { get: () => state.finished }
+	});
+	fn.clear = () => {
+		if (!state.called || !state.finished || state.cleared) return;
+		state.cleared = true;
+		state.value = void 0;
+	};
+	return fn;
+}
+function handleResult(state, value, error) {
+	state.error = error;
+	state.finished = true;
+	state.value = value;
+	const items = state.items.splice(0);
+	const { length } = items;
+	for (let index = 0; index < length; index += 1) {
+		const { reject, resolve } = items[index];
+		if (error) reject(value);
+		else resolve(value);
+	}
+}
+/**
+* Create a function that can only be called once, returning the same value on subsequent calls
+* @param callback Callback to use once
+* @returns Once callback
+*/
+function once(callback) {
+	assert(() => typeof callback === "function", MESSAGE_EXPECTATION);
+	const state = {
+		called: false,
+		cleared: false,
+		value: void 0
+	};
+	const fn = (...parameters) => {
+		if (state.cleared) throw new Error(MESSAGE_CLEARED);
+		if (state.called) return state.value;
+		state.called = true;
+		state.value = callback(...parameters);
+		return state.value;
+	};
+	Object.defineProperties(fn, {
+		called: { get: () => state.called },
+		cleared: { get: () => state.cleared }
+	});
+	fn.clear = () => {
+		if (!state.called || state.cleared) return;
+		state.cleared = true;
+		state.value = void 0;
+	};
+	return fn;
+}
+once.async = asyncOnce;
+var MESSAGE_CLEARED = "Once has been cleared";
+var MESSAGE_EXPECTATION = "Once expected a function";
+export { once };

package/dist/index.js

@@ -42,6 +42,7 @@ import { hslToHex, hslToRgb, hslToRgba } from "./color/space/hsl.js";
 import { getColor } from "./color/index.js";
 import { SizedMap } from "./sized/map.js";
 import { memoize } from "./function/memoize.js";
+import { once } from "./function/once.js";
 import { debounce, throttle } from "./function/index.js";
 import { RetryError, retry } from "./function/retry.js";
 import { isError, isOk, isResult } from "./internal/result.js";
@@ -76,4 +77,4 @@ import { QueueError, queue } from "./queue.js";
 import { getRandomBoolean, getRandomCharacters, getRandomColor, getRandomHex, getRandomItem, getRandomItems } from "./random.js";
 import { attempt } from "./result/index.js";
 import { SizedSet } from "./sized/set.js";
-export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, sum, take, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PromiseTimeoutError, QueueError, RetryError, SizedMap, SizedSet, attempt, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, equal, error, exists, filter, find, flatten, floor, flow, toResult as fromPromise, fromQuery, toPromise as fromResult, getArray, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getUuid, getValue, groupBy, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, indexOf, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, max, median, memoize, merge, min, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, shuffle, slice, smush, snakeCase, sort, splice, startsWith, sum, take, template, throttle, timed, times, titleCase, toMap, toPromise, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/package.json

@@ -10,7 +10,7 @@
 		"jsdom": "^28.1",
 		"oxfmt": "^0.36",
 		"oxlint": "^1.51",
-		"rolldown": "1.0.0-rc.6",
+		"rolldown": "1.0.0-rc.7",
 		"tslib": "^2.8",
 		"typescript": "^5.9",
 		"vite": "8.0.0-beta.16",
@@ -184,5 +184,5 @@
 	},
 	"type": "module",
 	"types": "./types/index.d.ts",
-	"version": "0.157.0"
-}
+	"version": "0.158.0"
+}

package/src/function/index.ts

@@ -37,5 +37,6 @@ export function throttle<Callback extends GenericCallback>(
 
 export {noop} from '../internal/function/misc';
 export {memoize, type Memoized, type MemoizedOptions} from './memoize';
+export {once} from './once';
 
 // #endregion

package/src/function/once.ts

@@ -0,0 +1,188 @@
+import type {
+	GenericAsyncCallback,
+	GenericCallback,
+	OnceAsyncCallback,
+	OnceCallback,
+} from '../models';
+import {assert} from './assert';
+
+// #region Types
+
+type OnceAsyncItem<Value> = {
+	reject: (reason?: unknown) => void;
+	resolve: (value: Value) => void;
+};
+
+type OnceAsyncState<Value> = {
+	error: boolean;
+	finished: boolean;
+	items: OnceAsyncItem<Value>[];
+} & OnceState<Value>;
+
+type OnceState<Value> = {
+	called: boolean;
+	cleared: boolean;
+	value: Value;
+};
+
+// #endregion
+
+// #region Functions
+
+/**
+ * Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+ * @param callback Callback to use once
+ * @returns Once callback
+ */
+function asyncOnce<Callback extends GenericAsyncCallback>(
+	callback: Callback,
+): OnceAsyncCallback<Callback> {
+	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);
+
+	const state: OnceAsyncState<Awaited<ReturnType<Callback>>> = {
+		called: false,
+		cleared: false,
+		error: false,
+		finished: false,
+		items: [],
+		value: undefined as never,
+	};
+
+	const fn = (...parameters: Parameters<Callback>): Promise<Awaited<ReturnType<Callback>>> => {
+		if (state.cleared) {
+			return Promise.reject(new Error(MESSAGE_CLEARED));
+		}
+
+		if (state.finished) {
+			return state.error ? Promise.reject(state.value) : Promise.resolve(state.value);
+		}
+
+		if (state.called) {
+			return new Promise<Awaited<ReturnType<Callback>>>((resolve, reject) => {
+				state.items.push({reject, resolve});
+			});
+		}
+
+		state.called = true;
+
+		return new Promise<Awaited<ReturnType<Callback>>>((resolve, reject) => {
+			state.items.push({reject, resolve});
+
+			void callback(...parameters)
+				.then(value => {
+					handleResult(state, value, false);
+				})
+				.catch(error => {
+					handleResult(state, error, true);
+				});
+		});
+	};
+
+	Object.defineProperties(fn, {
+		called: {
+			get: (): boolean => state.called,
+		},
+		cleared: {
+			get: (): boolean => state.cleared,
+		},
+		error: {
+			get: (): boolean => state.error,
+		},
+		finished: {
+			get: (): boolean => state.finished,
+		},
+	});
+
+	fn.clear = (): void => {
+		if (!state.called || !state.finished || state.cleared) {
+			return;
+		}
+
+		state.cleared = true;
+		state.value = undefined as never;
+	};
+
+	return fn as OnceAsyncCallback<Callback>;
+}
+
+function handleResult<Value>(state: OnceAsyncState<Value>, value: unknown, error: boolean): void {
+	state.error = error;
+	state.finished = true;
+	state.value = value as Value;
+
+	const items = state.items.splice(0);
+	const {length} = items;
+
+	for (let index = 0; index < length; index += 1) {
+		const {reject, resolve} = items[index];
+
+		if (error) {
+			reject(value);
+		} else {
+			resolve(value as Value);
+		}
+	}
+}
+
+/**
+ * Create a function that can only be called once, returning the same value on subsequent calls
+ * @param callback Callback to use once
+ * @returns Once callback
+ */
+export function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback> {
+	assert(() => typeof callback === 'function', MESSAGE_EXPECTATION);
+
+	const state: OnceState<ReturnType<Callback>> = {
+		called: false,
+		cleared: false,
+		value: undefined as never,
+	};
+
+	const fn = (...parameters: Parameters<Callback>): ReturnType<Callback> => {
+		if (state.cleared) {
+			throw new Error(MESSAGE_CLEARED);
+		}
+
+		if (state.called) {
+			return state.value;
+		}
+
+		state.called = true;
+
+		state.value = callback(...parameters);
+
+		return state.value;
+	};
+
+	Object.defineProperties(fn, {
+		called: {
+			get: (): boolean => state.called,
+		},
+		cleared: {
+			get: (): boolean => state.cleared,
+		},
+	});
+
+	fn.clear = (): void => {
+		if (!state.called || state.cleared) {
+			return;
+		}
+
+		state.cleared = true;
+		state.value = undefined as never;
+	};
+
+	return fn as OnceCallback<Callback>;
+}
+
+once.async = asyncOnce;
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE_CLEARED = 'Once has been cleared';
+
+const MESSAGE_EXPECTATION = 'Once expected a function';
+
+// #endregion

package/src/models.ts

@@ -140,6 +140,41 @@ export type NumericalValues<Item extends PlainObject> = {
 	[Key in keyof Item as Item[Key] extends number ? Key : never]: Item[Key];
 };
 
+/**
+ * An asynchronous function that can only be called once, returning the same value on subsequent calls
+ */
+export type OnceAsyncCallback<Callback extends GenericAsyncCallback> = {
+	/**
+	 * Did the callback's promise reject?
+	 */
+	readonly error: boolean;
+	/**
+	 * Has the callback finished?
+	 */
+	readonly finished: boolean;
+} & Callback &
+	OnceCallbackProperties;
+
+/**
+ * A callback function that can only be called once, returning the same value on subsequent calls
+ */
+export type OnceCallback<Callback extends GenericCallback> = Callback & OnceCallbackProperties;
+
+type OnceCallbackProperties = {
+	/**
+	 * Has the callback been called?
+	 */
+	readonly called: boolean;
+	/**
+	 * Has the callback's value been cleared?
+	 */
+	readonly cleared: boolean;
+	/**
+	 * Clear the callback's cached value
+	 */
+	clear: () => void;
+};
+
 /**
  * A generic object
  */

package/types/function/index.d.ts

@@ -17,3 +17,4 @@ export declare function debounce<Callback extends GenericCallback>(callback: Cal
 export declare function throttle<Callback extends GenericCallback>(callback: Callback, time?: number): CancelableCallback<Callback>;
 export { noop } from '../internal/function/misc';
 export { memoize, type Memoized, type MemoizedOptions } from './memoize';
+export { once } from './once';

package/types/function/once.d.ts

@@ -0,0 +1,17 @@
+import type { GenericAsyncCallback, GenericCallback, OnceAsyncCallback, OnceCallback } from '../models';
+/**
+ * Create an asynchronous function that can only be called once, rejecting or resolving the same result on subsequent calls
+ * @param callback Callback to use once
+ * @returns Once callback
+ */
+declare function asyncOnce<Callback extends GenericAsyncCallback>(callback: Callback): OnceAsyncCallback<Callback>;
+/**
+ * Create a function that can only be called once, returning the same value on subsequent calls
+ * @param callback Callback to use once
+ * @returns Once callback
+ */
+export declare function once<Callback extends GenericCallback>(callback: Callback): OnceCallback<Callback>;
+export declare namespace once {
+    var async: typeof asyncOnce;
+}
+export {};

package/types/models.d.ts

@@ -83,6 +83,37 @@ export type NumericalKeys<Value> = {
 export type NumericalValues<Item extends PlainObject> = {
     [Key in keyof Item as Item[Key] extends number ? Key : never]: Item[Key];
 };
+/**
+ * An asynchronous function that can only be called once, returning the same value on subsequent calls
+ */
+export type OnceAsyncCallback<Callback extends GenericAsyncCallback> = {
+    /**
+     * Did the callback's promise reject?
+     */
+    readonly error: boolean;
+    /**
+     * Has the callback finished?
+     */
+    readonly finished: boolean;
+} & Callback & OnceCallbackProperties;
+/**
+ * A callback function that can only be called once, returning the same value on subsequent calls
+ */
+export type OnceCallback<Callback extends GenericCallback> = Callback & OnceCallbackProperties;
+type OnceCallbackProperties = {
+    /**
+     * Has the callback been called?
+     */
+    readonly called: boolean;
+    /**
+     * Has the callback's value been cleared?
+     */
+    readonly cleared: boolean;
+    /**
+     * Clear the callback's cached value
+     */
+    clear: () => void;
+};
 /**
  * A generic object
  */