@oscarpalmer/atoms 0.217.0 → 0.219.0

package/dist/index.mjs

@@ -8,7 +8,7 @@ function getArrayCallback(value) {
 	switch (typeof value) {
 		case "function": return value;
 		case "number":
-		case "string": return typeof value === "string" && value.includes(".") ? void 0 : (obj) => obj[value];
+		case "string": return (obj) => obj?.[value];
 		default: return;
 	}
 }
@@ -21,6 +21,15 @@ function getArrayCallbacks(bool, key, value) {
 }
 //#endregion
 //#region src/internal/array/find.ts
+function addResult(result, mapped, flat) {
+	if (!flat) {
+		result.matched.push(mapped);
+		return;
+	}
+	const array = Array.isArray(mapped) ? mapped : [mapped];
+	const { length } = array;
+	for (let index = 0; index < length; index += 1) result.matched.push(array[index]);
+}
 function createFindParameters(original) {
 	const { length } = original;
 	return {
@@ -29,15 +38,65 @@ function createFindParameters(original) {
 		value: length === 1 && typeof original[0] !== "function" ? original[0] : original[1]
 	};
 }
+function findAbsoluteValueOrDefault(array, parameters, defaultValue, useDefaultValue, reversed) {
+	if (parameters.length === 0) {
+		if (Array.isArray(array) && array.length > 0) return reversed ? array.at(-1) : array[0];
+		return useDefaultValue ? defaultValue : void 0;
+	}
+	const index = findValue(ARRAY_FIND_VALUE_INDEX, array, parameters, reversed);
+	if (index === -1) return useDefaultValue ? defaultValue : void 0;
+	return array[index];
+}
+function findComplexValues(parameters) {
+	const { array, arrayLength, callback, limit, result, type, value } = parameters;
+	const keys = /* @__PURE__ */ new Set();
+	for (let arrayIndex = 0; arrayIndex < arrayLength; arrayIndex += 1) {
+		const arrayItem = array[arrayIndex];
+		const keyed = callback == null ? arrayItem : callback(arrayItem, arrayIndex, array);
+		const mapped = arrayItem;
+		if (type === "all" && Object.is(keyed, value) || type === "unique" && !keys.has(keyed)) {
+			keys.add(keyed);
+			result.matched.push(mapped);
+			if (result.matched.length >= limit) return result;
+		} else result.notMatched.push(arrayItem);
+	}
+	return result;
+}
+function findSimpleValue(array, value, findIndex, reversed) {
+	if (findIndex) return reversed ? array.lastIndexOf(value) : array.indexOf(value);
+	return reversed ? array.findLast((item) => Object.is(item, value)) : array.find((item) => Object.is(item, value));
+}
+function findSimpleValues(parameters) {
+	const { array, arrayLength, callback, flat, limit, map, result, value } = parameters;
+	const { after, before } = map ?? {};
+	const handler = callback ?? ((item) => Object.is(item, value));
+	for (let arrayIndex = 0; arrayIndex < arrayLength; arrayIndex += 1) {
+		const arrayItem = array[arrayIndex];
+		let mapped = before == null ? arrayItem : before(arrayItem, arrayIndex, array);
+		if (!flat || after != null) {
+			if (handler(mapped, arrayIndex, array)) {
+				mapped = after == null ? mapped : after(arrayItem, arrayIndex, array);
+				addResult(result, mapped, flat);
+				if (result.matched.length >= limit) return result;
+			} else result.notMatched.push(arrayItem);
+			continue;
+		}
+		const flatItems = Array.isArray(mapped) ? mapped : [mapped];
+		const flatLength = flatItems.length;
+		for (let flatIndex = 0; flatIndex < flatLength; flatIndex += 1) {
+			const flatItem = flatItems[flatIndex];
+			if (handler(flatItem, arrayIndex, array)) result.matched.push(flatItem);
+			else result.notMatched.push(flatItem);
+		}
+	}
+	return result;
+}
 function findValue(type, array, parameters, reversed) {
 	const findIndex = type === ARRAY_FIND_VALUE_INDEX;
 	if (!Array.isArray(array) || array.length === 0) return findIndex ? -1 : void 0;
 	const { bool, key, value } = createFindParameters(parameters);
 	const callbacks = getArrayCallbacks(bool, key);
-	if (callbacks?.bool == null && callbacks?.keyed == null) {
-		if (findIndex) return reversed ? array.lastIndexOf(value) : array.indexOf(value);
-		return reversed ? array.findLast((item) => Object.is(item, value)) : array.find((item) => Object.is(item, value));
-	}
+	if (callbacks?.bool == null && callbacks?.keyed == null) return findSimpleValue(array, value, findIndex, reversed);
 	if (callbacks.bool != null) {
 		const index = reversed ? array.findLastIndex(callbacks.bool) : array.findIndex(callbacks.bool);
 		return findIndex ? index : array[index];
@@ -52,59 +111,42 @@ function findValueInArray(array, callback, value, findIndex, reversed) {
 	}
 	return findIndex ? -1 : void 0;
 }
-function findAbsoluteValueOrDefault(array, parameters, defaultValue, useDefaultValue, reversed) {
-	if (parameters.length === 0) {
-		if (Array.isArray(array) && array.length > 0) return reversed ? array.at(-1) : array[0];
-		return useDefaultValue ? defaultValue : void 0;
-	}
-	const index = findValue(ARRAY_FIND_VALUE_INDEX, array, parameters, reversed);
-	return index > -1 ? array[index] : useDefaultValue ? defaultValue : void 0;
-}
-function findValues(type, array, parameters, mapper) {
+function findValues(type, array, parameters, options) {
 	const result = {
 		matched: [],
 		notMatched: []
 	};
-	if (!Array.isArray(array) || array.length === 0) return result;
-	const { length } = array;
+	if (!Array.isArray(array)) return result;
+	const arrayLength = array.length;
+	if (arrayLength === 0) return result;
 	const { bool, key, value } = createFindParameters(parameters);
 	const callbacks = getArrayCallbacks(bool, key);
-	if (type === "unique" && callbacks?.keyed == null && length >= 100) {
+	if (type === "unique" && callbacks?.keyed == null && arrayLength >= 100) {
 		result.matched = [...new Set(array)];
 		return result;
 	}
-	const mapCallback = getArrayCallback(mapper?.callback);
-	const mapReverse = mapper?.reverse ?? false;
-	const mapAfter = mapCallback == null ? void 0 : mapReverse ? void 0 : mapCallback;
-	const mapBefore = mapCallback == null ? void 0 : mapReverse ? mapCallback : void 0;
-	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];
-			const transformed = mapBefore?.(item, index, array) ?? item;
-			if (callback(transformed, index, array)) result.matched.push(mapAfter?.(item, index, array) ?? transformed);
-			else result.notMatched.push(item);
-		}
-		return result;
-	}
-	const keys = /* @__PURE__ */ new Set();
-	for (let index = 0; index < length; index += 1) {
-		const item = array[index];
-		let keyed;
-		let transformed;
-		if (mapBefore == null) {
-			keyed = callbacks?.keyed?.(item, index, array) ?? item;
-			transformed = item;
-		} else {
-			transformed = mapBefore(item, index, array);
-			keyed = callbacks?.keyed?.(transformed, index, array) ?? transformed;
-		}
-		if (type === "all" && Object.is(keyed, value) || type === "unique" && !keys.has(keyed)) {
-			keys.add(keyed);
-			result.matched.push(mapAfter?.(item, index, array) ?? transformed);
-		} else result.notMatched.push(item);
-	}
-	return result;
+	const limit = options?.limit ?? Number.POSITIVE_INFINITY;
+	const flat = options?.map?.flat ?? false;
+	const mapCallback = getArrayCallback(options?.map?.callback);
+	const mapReverse = options?.map?.reverse ?? false;
+	let map;
+	if (mapCallback != null) map = {
+		before: mapReverse ? mapCallback : void 0,
+		after: mapReverse ? void 0 : mapCallback
+	};
+	const simple = callbacks?.bool != null || type === "all" && key == null;
+	const findParameters = {
+		array,
+		arrayLength,
+		flat,
+		limit,
+		map,
+		result,
+		type,
+		value,
+		callback: simple ? callbacks?.bool : callbacks?.keyed
+	};
+	return simple ? findSimpleValues(findParameters) : findComplexValues(findParameters);
 }
 //#endregion
 //#region src/array/filter.ts
@@ -431,6 +473,21 @@ const arrayMatchStarts = /* @__PURE__ */ new Set([ARRAY_MATCH_COMPARISON_START,
 function endsWithArray(haystack, needle, key) {
 	return arrayMatchEndings.has(getPosition(haystack, needle, key)[1]);
 }
+function evaluatePosition(haystack, haystackLength, needle, needleLength, key) {
+	const callback = getArrayCallback(key);
+	const limit = haystackLength - needleLength + 1;
+	let needleValues = callback == null ? needle : needle.slice();
+	if (callback != null) for (let needleIndex = 0; needleIndex < needleLength; needleIndex += 1) needleValues[needleIndex] = callback(needle[needleIndex], needleIndex, needle);
+	for (let haystackIndex = 0; haystackIndex < limit; haystackIndex += 1) {
+		if (!inHaystack(haystack, haystackIndex, needleValues, 0, callback)) continue;
+		if (needleLength === 1) return [haystackIndex, getName(haystackIndex, haystackLength, needleLength)];
+		for (let needleIndex = 1; needleIndex < needleLength; needleIndex += 1) {
+			if (!inHaystack(haystack, haystackIndex, needleValues, needleIndex, callback)) break;
+			if (needleIndex === needleLength - 1) return [haystackIndex, getName(haystackIndex, haystackLength, needleLength)];
+		}
+	}
+	return arrayMatchOutside;
+}
 function getArrayComparison(haystack, needle, key) {
 	return getPosition(haystack, needle, key)[1];
 }
@@ -444,23 +501,12 @@ function getPosition(haystack, needle, key) {
 	const needleLength = needle.length;
 	if (haystackLength === 0 || needleLength === 0) return arrayMatchOutside;
 	if (needleLength > haystackLength) return arrayMatchOutside;
-	const callback = getArrayCallback(key);
-	const limit = haystackLength - needleLength + 1;
-	let needleValues = callback == null ? needle : needle.slice();
-	if (callback != null) for (let needleIndex = 0; needleIndex < needleLength; needleIndex += 1) needleValues[needleIndex] = callback(needle[needleIndex], needleIndex, needle);
-	for (let haystackIndex = 0; haystackIndex < limit; haystackIndex += 1) {
-		let haystackItem = haystack[haystackIndex];
-		let haystackValue = callback?.(haystackItem, haystackIndex, haystack) ?? haystackItem;
-		if (!Object.is(haystackValue, needleValues[0])) continue;
-		if (needleLength === 1) return [haystackIndex, getName(haystackIndex, haystackLength, needleLength)];
-		for (let needleIndex = 1; needleIndex < needleLength; needleIndex += 1) {
-			haystackItem = haystack[haystackIndex + needleIndex];
-			haystackValue = callback?.(haystackItem, haystackIndex + needleIndex, haystack) ?? haystackItem;
-			if (!Object.is(haystackValue, needleValues[needleIndex])) break;
-			if (needleIndex === needleLength - 1) return [haystackIndex, getName(haystackIndex, haystackLength, needleLength)];
-		}
-	}
-	return arrayMatchOutside;
+	return evaluatePosition(haystack, haystackLength, needle, needleLength, key);
+}
+function inHaystack(haystack, haystackIndex, needleValues, needleIndex, callback) {
+	const haystackItem = haystack[haystackIndex + needleIndex];
+	const haystackValue = callback?.(haystackItem, haystackIndex + needleIndex, haystack) ?? haystackItem;
+	return Object.is(haystackValue, needleValues[needleIndex]);
 }
 function includesArray(haystack, needle, key) {
 	return !arrayMatchOutsides.has(getPosition(haystack, needle, key)[1]);
@@ -479,6 +525,13 @@ function startsWithArray(haystack, needle, key) {
 * @param value Number to round down
 * @param decimals Number of decimal places to round to _(defaults to `0`)_
 * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+*
+* @example
+* ```typescript
+* floor(10.567, 2); // => 10.56
+* floor(10.567);    // => 10
+* floor('abc');       // => Number.NaN
+* ```
 */
 function floor(value, decimals) {
 	return roundNumber(Math.floor, value, decimals);
@@ -489,6 +542,13 @@ function floor(value, decimals) {
 * @param value Number to round
 * @param decimals Number of decimal places to round to _(defaults to `0`)_
 * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+*
+* @example
+* ```typescript
+* round(10.567, 2); // => 10.57
+* round(10.567);    // => 11
+* round('abc');       // => Number.NaN
+* ```
 */
 function round(value, decimals) {
 	return roundNumber(Math.round, value, decimals);
@@ -501,12 +561,22 @@ function roundNumber(callback, value, decimals) {
 }
 //#endregion
 //#region src/internal/random.ts
+/**
+* Get a random number between 0 _(inclusive)_ and 1 _(exclusive)_
+*
+* @returns Random number
+*/
+function getRandom() {
+	/* istanbul ignore if */
+	if (globalThis.crypto == null) return Math.random();
+	return globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint32Array(1))[0] / RANDOM_DIVISOR;
+}
 function getRandomFloatingNumberValue(inclusive, minimum, maximum) {
 	let maxFloat = isNumber(maximum) && maximum <= Number.MAX_SAFE_INTEGER ? maximum : Number.MAX_SAFE_INTEGER;
 	let minFloat = isNumber(minimum) && minimum >= Number.MIN_SAFE_INTEGER ? minimum : Number.MIN_SAFE_INTEGER;
 	if (minFloat === maxFloat) return minFloat;
 	if (minFloat > maxFloat) [minFloat, maxFloat] = [maxFloat, minFloat];
-	return Math.random() * (maxFloat + (inclusive ? 1 : 0) - minFloat) + minFloat;
+	return getRandom() * (maxFloat + (inclusive ? 1 : 0) - minFloat) + minFloat;
 }
 /**
 * Get a random floating-point number
@@ -528,6 +598,7 @@ function getRandomFloatingNumber(minimum, maximum) {
 function getRandomInteger(minimum, maximum) {
 	return floor(getRandomFloatingNumberValue(true, minimum, maximum));
 }
+const RANDOM_DIVISOR = 2 ** 32;
 //#endregion
 //#region src/internal/array/shuffle.ts
 /**
@@ -535,6 +606,11 @@ function getRandomInteger(minimum, maximum) {
 *
 * @param array Original array
 * @returns Shuffled array
+*
+* @example
+* ```typescript
+* shuffle([1, 2, 3]); // => [3, 1, 2] (maybe? it's random, you know)
+* ```
 */
 function shuffle(array) {
 	if (!Array.isArray(array)) return [];
@@ -554,8 +630,14 @@ function compareSets(type, first, second, key) {
 	const isDifference = type === ARRAY_SETS_COMPARE_DIFFERENCE;
 	const isIntersection = type === ARRAY_SETS_COMPARE_INTERSECTION;
 	const isUnion = type === ARRAY_SETS_COMPARE_UNION;
-	if (first.length === 0) return isDifference ? first.slice() : isIntersection ? [] : second.slice();
+	if (first.length === 0) {
+		if (isDifference) return first.slice();
+		return isIntersection ? [] : second.slice();
+	}
 	if (!Array.isArray(second) || second.length === 0) return isIntersection ? [] : first.slice();
+	return getComparison(first, second, isIntersection, isUnion, key);
+}
+function getComparison(first, second, isIntersection, isUnion, key) {
 	const callback = getArrayCallback(key);
 	const values = isUnion ? first : second;
 	let { length } = values;
@@ -668,7 +750,10 @@ function getAggregateCallback(key) {
 }
 function getAggregated(type, array, key, first) {
 	const aggregation = aggregate(type, array, key, first);
-	if (aggregation.count === 0) return aggregation.array ? aggregation.first ? void 0 : [] : NaN;
+	if (aggregation.count === 0) {
+		if (aggregation.array) return aggregation.first ? void 0 : [];
+		return NaN;
+	}
 	if (aggregation.array) {
 		const array = aggregation.items[aggregation.value];
 		return aggregation.first ? array[0] : array;
@@ -696,7 +781,7 @@ const aggregators = {
 //#endregion
 //#region src/internal/array/insert.ts
 function insertChunkedValues(type, array, items, start, deleteCount) {
-	const actualDeleteCount = deleteCount < 0 ? 0 : deleteCount;
+	const actualDeleteCount = max([deleteCount, 0]);
 	const actualStart = min([max([0, start]), array.length]);
 	const chunked = chunk(items);
 	const lastIndex = chunked.length - 1;
@@ -719,7 +804,7 @@ function insertValues(type, array, items, start, deleteCount) {
 //#endregion
 //#region src/array/insert.ts
 function insert(array, indexOrItems, items) {
-	return insertValues(ARRAY_INSERT_TYPE_INSERT, array, items == null ? indexOrItems : items, typeof indexOrItems === "number" ? indexOrItems : array?.length, 0);
+	return insertValues(ARRAY_INSERT_TYPE_INSERT, array, items ?? indexOrItems, typeof indexOrItems === "number" ? indexOrItems : array?.length, 0);
 }
 //#endregion
 //#region src/array/intersection.ts
@@ -758,6 +843,12 @@ function push(array, pushed) {
 *
 * @param array Array to reverse
 * @returns Reversed array
+*
+* @example
+* ```typescript
+* reverse([1, 2, 3]);       // => [3, 2, 1]
+* reverse(['a', 'b', 'c']); // => ['c', 'b', 'a']
+* ```
 */
 function reverse(array) {
 	if (!Array.isArray(array)) return [];
@@ -775,7 +866,7 @@ function reverse(array) {
 //#endregion
 //#region src/array/single.ts
 function single(array, ...parameters) {
-	const { matched } = findValues("all", array, parameters);
+	const { matched } = findValues("all", array, parameters, { limit: 2 });
 	if (matched.length > 1) throw new Error(SINGLE_MESSAGE);
 	return matched[0];
 }
@@ -789,34 +880,47 @@ function extract(type, array, first, second) {
 	if (!Array.isArray(array)) return [];
 	const { length } = array;
 	if (length === 0) return [];
-	const isTake = type === ARRAY_SLICE_TAKE;
-	if (typeof first === "number") {
-		if (Math.abs(first) >= length) return isTake ? array.slice() : [];
-		if (first === 0) return isTake ? [] : array.slice();
-		if (isTake) return first >= 0 ? array.slice(0, first) : array.slice(array.length + first);
-		return first >= 0 ? array.slice(first) : array.slice(0, array.length + first);
-	}
-	const callbacks = second == null ? getArrayCallbacks(first) : getArrayCallbacks(void 0, void 0, first);
+	const take = type === ARRAY_SLICE_TAKE;
+	return typeof first === "number" ? getSlice(array, length, first, take) : extractSlice(array, length, first, second, take);
+}
+function extractSlice(array, length, first, second, take) {
+	const callbacks = getCallbacks(first, second);
+	if (callbacks?.bool == null && callbacks?.value == null) return take ? array.slice() : [];
 	const isBoolean = callbacks?.bool != null;
-	if (callbacks?.bool == null && callbacks?.value == null) return isTake ? array.slice() : [];
 	const extracted = [];
 	let push = false;
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
-		const matches = isBoolean ? callbacks.bool(item, index, array) : Object.is(callbacks.value(item, index, array), second);
-		if (isTake) {
-			if (isBoolean ? !matches : matches) break;
+		const matches = isMatch(item, index, array, callbacks, second, isBoolean);
+		const reached = isBoolean ? !matches : matches;
+		if (take && reached) break;
+		if (push || take) {
 			extracted.push(item);
 			continue;
 		}
-		if (push) extracted.push(item);
-		else if (isBoolean ? !matches : matches) {
+		if (reached) {
 			push = true;
 			if (isBoolean) extracted.push(item);
 		}
 	}
 	return extracted;
 }
+function getCallbacks(first, second) {
+	let callbacks;
+	if (second == null) callbacks = getArrayCallbacks(first);
+	else callbacks = getArrayCallbacks(void 0, void 0, first);
+	return callbacks;
+}
+function getSlice(array, length, amount, take) {
+	if (Math.abs(amount) >= length) return take ? array.slice() : [];
+	if (amount === 0) return take ? [] : array.slice();
+	if (take) return amount >= 0 ? array.slice(0, amount) : array.slice(length + amount);
+	return amount >= 0 ? array.slice(amount) : array.slice(0, length + amount);
+}
+function isMatch(item, index, array, callbacks, second, isBoolean) {
+	if (isBoolean) return callbacks.bool(item, index, array);
+	return Object.is(callbacks.value(item, index, array), second);
+}
 function slice(array, first, second) {
 	if (!Array.isArray(array) || array.length === 0) return [];
 	const firstIsNumber = typeof first === "number";
@@ -993,22 +1097,28 @@ move.indices = moveIndices;
 move.toIndex = moveToIndex;
 //#endregion
 //#region src/array/select.ts
-function filterAndMap(array, ...parameters) {
-	return selectValues(array, parameters);
+function filterAndFlatMap(array, filter, mapper) {
+	return selectValues(array, filter, mapper, true, false);
+}
+function filterAndMap(array, filter, mapper) {
+	return selectValues(array, filter, mapper, false, false);
 }
-function mapAndFilter(array, ...parameters) {
-	return findValues("all", array, parameters, {
-		callback: parameters.shift(),
-		reverse: true
-	}).matched;
+function flatMapAndFilter(array, mapper, filter) {
+	return selectValues(array, filter, mapper, true, true);
 }
-function selectValues(array, parameters) {
-	return findValues("all", array, parameters, {
-		callback: parameters.pop(),
-		reverse: false
-	}).matched;
+function mapAndFilter(array, mapper, filter) {
+	return selectValues(array, filter, mapper, false, true);
 }
+function selectValues(array, filter, mapper, flat, reverse) {
+	return findValues("all", array, [filter], { map: {
+		flat,
+		reverse,
+		callback: mapper
+	} }).matched;
+}
+filterAndMap.flat = filterAndFlatMap;
 filterAndMap.reverse = mapAndFilter;
+mapAndFilter.flat = flatMapAndFilter;
 //#endregion
 //#region src/models/value/value.misc.model.ts
 const COMPARE_NAME = "compare";
@@ -1022,7 +1132,7 @@ const VALUE_MISC_NESTED_MESSAGE_UNSAFE = "Access to this property is not allowed
 //#endregion
 //#region src/models/string/string.misc.model.ts
 const STRING_EXPRESSION_IGNORED = /(^|\.)(__proto__|constructor|prototype)(\.|$)/i;
-const STRING_EXPRESSION_WORDS = /[^\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]+/g;
+const STRING_EXPRESSION_WORDS = /([^\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]+)/g;
 const STRING_EXPRESSION_WHITESPACE_PREFIX = /^(\s+)/;
 const STRING_MATCH_ENDS_WITH = "endsWith";
 const STRING_MATCH_INCLUDES = "includes";
@@ -1079,18 +1189,11 @@ error.is = isError;
 ok.is = isOk;
 //#endregion
 //#region src/result/misc.ts
-/**
-* Converts a _Result_ to a _Promise_
-*
-* Resolves if ok, rejects for error
-*
-* @param result _Result_ to convert
-* @returns Promised result
-*/
 async function toPromise(result) {
 	const actual = typeof result === "function" ? result() : result;
-	if (!isResult(actual)) return Promise.reject(new Error(RESULT_MESSAGE_PROMISE));
-	return isOk(actual) ? Promise.resolve(actual.value) : Promise.reject(actual.error);
+	if (!isResult(actual)) throw new TypeError(RESULT_MESSAGE_PROMISE);
+	if (isOk(actual)) return actual.value;
+	throw actual.error;
 }
 const RESULT_MESSAGE_PROMISE = "toPromise expected to receive a Result";
 //#endregion
@@ -1102,15 +1205,15 @@ async function asyncAttempt(value, err) {
 		else result = value;
 		if (result instanceof Promise) result = await result;
 		return ok(result);
-	} catch (thrown) {
-		return getError(err ?? thrown, err == null ? void 0 : thrown);
+	} catch (error) {
+		return getError(err ?? error, err == null ? void 0 : error);
 	}
 }
 function attempt(callback, err) {
 	try {
 		return ok(callback());
-	} catch (thrown) {
-		return getError(err ?? thrown, err == null ? void 0 : thrown);
+	} catch (error) {
+		return getError(err ?? error, err == null ? void 0 : error);
 	}
 }
 attempt.async = asyncAttempt;
@@ -1141,9 +1244,15 @@ function getString(value) {
 	const asString = String(value.valueOf?.() ?? value);
 	return asString.startsWith("[object ") ? JSON.stringify(value) : asString;
 }
+/**
+* @internal
+*/
 function ignoreKey(key) {
 	return STRING_EXPRESSION_IGNORED.test(key);
 }
+/**
+* @internal
+*/
 function interpolate(strings, values) {
 	const { length } = strings;
 	let interpolated = "";
@@ -1161,6 +1270,14 @@ function interpolate(strings, values) {
 * @param array Array of values
 * @param delimiter Delimiter to use between values
 * @returns Joined string
+* @example
+* ```typescript
+* join(['a', 'b', 'c']);          // => 'abc'
+* join(['a', 'b', 'c'], ', ');   // => 'a, b, c'
+* join(['a', '', 'c']);           // => 'ac'
+* join([null, 'b', undefined]);   // => 'b'
+* join([]);                       // => ''
+* ```
 */
 function join(array, delimiter) {
 	if (!Array.isArray(array)) return "";
@@ -1176,9 +1293,15 @@ function join(array, delimiter) {
 function tryCallback(value, callback) {
 	return unwrap(attempt(() => callback(value)), value);
 }
+/**
+* @internal
+*/
 function tryDecode(value) {
 	return tryCallback(value, decodeURIComponent);
 }
+/**
+* @internal
+*/
 function tryEncode(value) {
 	return tryCallback(value, encodeURIComponent);
 }
@@ -1189,7 +1312,8 @@ function tryEncode(value) {
 * @returns Array of words found in the string
 */
 function words(value) {
-	return typeof value === "string" ? value.match(STRING_EXPRESSION_WORDS) ?? [] : [];
+	if (typeof value === "string") return value.match(STRING_EXPRESSION_WORDS) ?? [];
+	return [];
 }
 //#endregion
 //#region src/internal/value/handlers.ts
@@ -1442,7 +1566,7 @@ function isSortedArray(array) {
 	let offset = 0;
 	if (length >= 100) {
 		offset = round(length / 10);
-		offset = offset > 100 ? 100 : offset;
+		offset = min([offset, 100]);
 		for (let index = 0; index < offset; index += 1) {
 			const [firstItem, firstOffset] = [array[index], array[index + 1]];
 			const [secondItem, secondOffset] = [array[length - index - 2], array[length - index - 1]];
@@ -2088,8 +2212,11 @@ async function asyncRetry(callback, options) {
 	if (typeof callback !== "function") throw new TypeError(RETRY_MESSAGE_EXPECTATION);
 	async function handle() {
 		const result = await asyncAttempt(async () => callback());
-		if (result.ok) resolver(result.value);
-		else if (attempts >= times || !when(result.error)) rejector(new RetryError(RETRY_MESSAGE_FAILED, result.error));
+		if (result.ok) {
+			resolver(result.value);
+			return;
+		}
+		if (attempts >= times || !when(result.error)) rejector(new RetryError(RETRY_MESSAGE_FAILED, result.error));
 		else {
 			attempts += 1;
 			limiter.run();
@@ -2160,8 +2287,15 @@ const EXPRESSION_WHITESPACE_ONLY = /^\s*$/;
 *
 * @param value Value to check
 * @param minimum Minimum value
-* @param maximum Maximum value
+* @param maximum Maximum value _(inclusive)_
 * @returns `true` if the value is between the minimum and maximum, otherwise `false`
+*
+* @example
+* ```typescript
+* between(5, 1, 10); // => true
+* between(0, 1, 10); // => false
+* between(10, 10, 10); // => true
+* ```
 */
 function between(value, minimum, maximum) {
 	if (![
@@ -2170,7 +2304,8 @@ function between(value, minimum, maximum) {
 		maximum
 	].every(isNumber)) return false;
 	if (Object.is(minimum, maximum)) return Object.is(value, minimum);
-	return value >= (maximum > minimum ? minimum : maximum) && value <= (maximum > minimum ? maximum : minimum);
+	const maximumValue = max([maximum, minimum]);
+	return value >= min([maximum, minimum]) && value <= maximumValue;
 }
 /**
 * Clamp a number between a minimum and maximum value
@@ -2203,6 +2338,17 @@ function clamp(value, minimum, maximum, loop) {
 *
 * @param value Original value
 * @returns Original value as a number, or `Number.NaN` if the value is unable to be parsed
+*
+* @example
+* ```typescript
+* getNumber(null)       // => Number.NaN
+* getNumber('foo')      // => Number.NaN
+* getNumber('123')        // => 123
+* getNumber(true)       // => 1
+* getNumber([1, 2, 3])  // => Number.NaN
+* getNumber({a: 1})     // => Number.NaN
+* getNumber(() => 123)  // => 123
+* ```
 */
 function getNumber(value) {
 	if (typeof value === "number") return value;
@@ -2435,6 +2581,14 @@ const STRING_REPLACEMENT_CAMEL_CASE = "$1-$2";
 *
 * @param value String to convert
 * @returns Camel-cased string
+*
+* @example
+* ```typescript
+* camelCase('this is camel case'); // => 'thisIsCamelCase'
+* camelCase('ThisIsCamelCase');    // => 'thisIsCamelCase'
+* camelCase('this-is-camel-case'); // => 'thisIsCamelCase'
+* camelCase('this_is_camel_case'); // => 'thisIsCamelCase'
+* ```
 */
 function camelCase(value) {
 	return toCase(STRING_CASE_CAMEL, value, true, false);
@@ -2444,6 +2598,14 @@ function camelCase(value) {
 *
 * @param value String to capitalize
 * @returns Capitalized string
+*
+* @example
+* ```typescript
+* capitalize('this is a test'); // => 'This is a test'
+* capitalize('This Is A Test'); // => 'This is a test'
+* capitalize('t');              // => 'T'
+* capitalize('');               // => ''
+* ```
 */
 function capitalize(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -2455,6 +2617,14 @@ function capitalize(value) {
 *
 * @param value String to convert
 * @returns Kebab-cased string
+*
+* @example
+* ```typescript
+* kebabCase('this is kebab case'); // => 'this-is-kebab-case'
+* kebabCase('ThisIsKebabCase');    // => 'this-is-kebab-case'
+* kebabCase('this-is-kebab-case'); // => 'this-is-kebab-case'
+* kebabCase('this_is_kebab_case'); // => 'this-is-kebab-case'
+* ```
 */
 function kebabCase(value) {
 	return toCase(STRING_CASE_KEBAB, value, false, false);
@@ -2464,6 +2634,13 @@ function kebabCase(value) {
 *
 * @param value String to convert
 * @returns Lower-cased string
+*
+* @example
+* ```typescript
+* lowerCase('THIS IS A TEST'); // => 'this is a test'
+* lowerCase('this is a test'); // => 'this is a test'
+* lowerCase('t');              // => 't'
+* ```
 */
 function lowerCase(value) {
 	if (typeof value !== "string") return "";
@@ -2475,6 +2652,14 @@ function lowerCase(value) {
 *
 * @param value String to convert
 * @returns Pascal-cased string
+*
+* @example
+* ```typescript
+* pascalCase('this is pascal case'); // => 'ThisIsPascalCase'
+* pascalCase('ThisIsPascalCase');    // => 'ThisIsPascalCase'
+* pascalCase('this-is-pascal-case'); // => 'ThisIsPascalCase'
+* pascalCase('this_is_pascal_case'); // => 'ThisIsPascalCase'
+* ```
 */
 function pascalCase(value) {
 	return toCase(STRING_CASE_PASCAL, value, true, true);
@@ -2484,6 +2669,14 @@ function pascalCase(value) {
 *
 * @param value String to convert
 * @returns Snake-cased string
+*
+* @example
+* ```typescript
+* snakeCase('this is snake case'); // => 'this_is_snake_case'
+* snakeCase('ThisIsSnakeCase');    // => 'this_is_snake_case'
+* snakeCase('this-is-snake-case'); // => 'this_is_snake_case'
+* snakeCase('this_is_snake_case'); // => 'this_is_snake_case'
+* ```
 */
 function snakeCase(value) {
 	return toCase(STRING_CASE_SNAKE, value, false, false);
@@ -2493,6 +2686,14 @@ function snakeCase(value) {
 *
 * @param value String to convert
 * @returns Title-cased string
+*
+* @example
+* ```typescript
+* titleCase('this is a test'); // => 'This Is A Test'
+* titleCase('This Is A Test'); // => 'This Is A Test'
+* titleCase('t');              // => 'T'
+* titleCase('');               // => ''
+* ```
 */
 function titleCase(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -2535,6 +2736,14 @@ function toCaseCallback(value) {
 *
 * @param value String to convert
 * @returns Upper-cased string
+*
+* @example
+* ```typescript
+* upperCase('this is a test'); // => 'THIS IS A TEST'
+* upperCase('This Is A Test'); // => 'THIS IS A TEST'
+* upperCase('t');              // => 'T'
+* upperCase('');               // => ''
+* ```
 */
 function upperCase(value) {
 	if (typeof value !== "string" || value.length === 0) return "";
@@ -2619,7 +2828,7 @@ function equalArray(first, second, options) {
 	let offset = 0;
 	if (length >= 100) {
 		offset = round(length / 10);
-		offset = offset > 100 ? 100 : offset;
+		offset = min([offset, 100]);
 		for (let index = 0; index < offset; index += 1) if (!(equalValue(first[index], second[index], options) && equalValue(first[length - index - 1], second[length - index - 1], options))) return false;
 	}
 	const end = length - offset;
@@ -2776,6 +2985,8 @@ const PLAN_FAILURE_ASYNC = "asyncFailure";
 const PLAN_FAILURE_SYNC = "failure";
 const PLAN_MESSAGE_PLAN_INPUT = "plan requires a generator function";
 const PLAN_MESSAGE_RUN_INPUT = "run requires a plan or a generator function";
+const PLAN_MESSAGE_USE_NESTED_FN = "Cannot use nested functions with 'use'";
+const PLAN_MESSAGE_USE_SYNC_ASYNC = "Cannot use asynchronous values with 'use'";
 const PLAN_STEP_ASYNC = "asyncStep";
 const PLAN_STEP_SYNC = "step";
 const PLAN_SUCCESS_ASYNC = "asyncSuccess";
@@ -2802,7 +3013,7 @@ function createAborter(value, onAbort) {
 //#region src/internal/plan/plan.generate.ts
 async function asyncGenerate(input, unwrap, first, second) {
 	const aborter = createAborter(second ?? first, noop);
-	if (aborter != null && aborter.signal.aborted) throw aborter.signal.reason;
+	if (aborter?.signal.aborted) throw aborter.signal.reason;
 	const parameters = Array.isArray(first) ? first : [];
 	let generator;
 	if (typeof input === "function") generator = input(...parameters);
@@ -2811,7 +3022,7 @@ async function asyncGenerate(input, unwrap, first, second) {
 	let lastValue;
 	try {
 		while (true) {
-			if (aborter != null && aborter.signal.aborted) await generator.throw(aborter.signal.reason);
+			if (aborter?.signal.aborted) await generator.throw(aborter.signal.reason);
 			const next = await generator.next(lastValue);
 			const done = next.done === true;
 			const { value } = next;
@@ -2827,7 +3038,7 @@ async function asyncGenerate(input, unwrap, first, second) {
 		aborter?.cancel();
 		await generator.return(lastValue);
 	}
-	if (aborter != null && aborter.signal.aborted) throw aborter.signal.reason;
+	if (aborter?.signal.aborted) throw aborter.signal.reason;
 	if (success) return unwrap && isOk(lastValue) ? lastValue.value : lastValue;
 	throw lastValue;
 }
@@ -3004,21 +3215,6 @@ function attemptRun(input, ...parameters) {
 }
 attemptRun.async = asyncAttemptRun;
 //#endregion
-//#region src/plan/run.ts
-function asyncRun(input, first, second) {
-	if (isAsyncPlan(input)) return asyncGenerate(input[PLAN_SYMBOL], false, first, second);
-	if (isAsyncGeneratorFunction(input)) return asyncGenerate(input, false, first, second);
-	throw new Error(PLAN_MESSAGE_RUN_INPUT);
-}
-function run(input, ...parameters) {
-	if (isPlan(input)) return input.run(...parameters);
-	if (isGeneratorFunction(input)) return generate(input, parameters, false);
-	throw new Error(PLAN_MESSAGE_RUN_INPUT);
-}
-asyncRun.attempt = asyncAttemptRun;
-run.async = asyncRun;
-run.attempt = attemptRun;
-//#endregion
 //#region src/plan/index.ts
 function AsyncPlan(generator) {
 	this[PLAN_SYMBOL] = {
@@ -3099,6 +3295,21 @@ function succeed(value) {
 fail.async = asyncFail;
 succeed.async = asyncSucceed;
 //#endregion
+//#region src/plan/run.ts
+function asyncRun(input, first, second) {
+	if (isAsyncPlan(input)) return asyncGenerate(input[PLAN_SYMBOL], false, first, second);
+	if (isAsyncGeneratorFunction(input)) return asyncGenerate(input, false, first, second);
+	throw new Error(PLAN_MESSAGE_RUN_INPUT);
+}
+function run(input, ...parameters) {
+	if (isPlan(input)) return input.run(...parameters);
+	if (isGeneratorFunction(input)) return generate(input, parameters, false);
+	throw new Error(PLAN_MESSAGE_RUN_INPUT);
+}
+asyncRun.attempt = asyncAttemptRun;
+run.async = asyncRun;
+run.attempt = attemptRun;
+//#endregion
 //#region src/plan/use.ts
 function AsyncStep(generator) {
 	this[PLAN_SYMBOL] = {
@@ -3119,7 +3330,7 @@ function asyncUse(value) {
 		let actual = value;
 		if (typeof actual === "function") actual = actual();
 		actual = await actual;
-		if (typeof actual === "function") throw new Error();
+		if (typeof actual === "function") throw new TypeError(PLAN_MESSAGE_USE_NESTED_FN);
 		if (typeof actual === "object" && actual !== null && PLAN_SYMBOL in actual) return yield* actual;
 		if (isAsyncGenerator(actual) || isGenerator(actual)) return yield* actual;
 		if (isError(actual)) {
@@ -3157,8 +3368,8 @@ function use(value) {
 	});
 }
 function validateUseInput(value, resolved) {
-	if (value instanceof Promise || isAsyncFailure(value) || isAsyncGenerator(value) || isAsyncGeneratorFunction(value) || isAsyncPlan(value) || isAsyncStep(value) || isAsyncSuccess(value)) throw new Error();
-	if (resolved && typeof value === "function") throw new Error();
+	if (value instanceof Promise || isAsyncFailure(value) || isAsyncGenerator(value) || isAsyncGeneratorFunction(value) || isAsyncPlan(value) || isAsyncStep(value) || isAsyncSuccess(value)) throw new Error(PLAN_MESSAGE_USE_SYNC_ASYNC);
+	if (resolved && typeof value === "function") throw new Error(PLAN_MESSAGE_USE_NESTED_FN);
 }
 use.async = asyncUse;
 //#endregion
@@ -3277,6 +3488,9 @@ function isRejected(value) {
 function cancelable(executor) {
 	return new CancelablePromise(executor);
 }
+/**
+* @internal
+*/
 function handleResult(status, parameters) {
 	const { aborter, complete, data, handlers, index, key, value } = parameters;
 	if (aborter?.signal.aborted ?? false) return;
@@ -3285,25 +3499,31 @@ function handleResult(status, parameters) {
 		handlers.reject(value);
 		return;
 	}
-	data.result[key] = !complete ? value : status === "fulfilled" ? {
+	let resultValue;
+	if (complete) resultValue = status === "fulfilled" ? {
 		status,
 		value
 	} : {
 		status,
 		reason: value
 	};
+	else resultValue = value;
+	data.result[key] = resultValue;
 	if (index === data.last) {
 		aborter?.cancel();
 		handlers.resolve(data.result);
 	}
 }
+/**
+* @internal
+*/
 function settlePromise(settler, value, aborter) {
 	aborter?.cancel();
 	settler(value);
 }
 async function toResult(value) {
 	const actual = typeof value === "function" ? value() : value;
-	if (!(actual instanceof Promise)) return Promise.reject(/* @__PURE__ */ new TypeError(PROMISE_MESSAGE_EXPECTATION_RESULT));
+	if (!(actual instanceof Promise)) throw new TypeError(PROMISE_MESSAGE_EXPECTATION_RESULT);
 	return actual.then((result) => ok(result)).catch((reason) => error(reason));
 }
 //#endregion
@@ -3327,6 +3547,9 @@ function delay(options) {
 }
 //#endregion
 //#region src/promise/timed.ts
+/**
+* @internal
+*/
 async function getTimedPromise(promise, time, signal) {
 	const aborter = createAborter(signal, () => {
 		limiter.cancel();
@@ -3345,18 +3568,18 @@ async function getTimedPromise(promise, time, signal) {
 	});
 }
 async function timed(promise, options) {
-	if (!(promise instanceof Promise)) return Promise.reject(/* @__PURE__ */ new TypeError(PROMISE_MESSAGE_EXPECTATION_TIMED));
+	if (!(promise instanceof Promise)) throw new TypeError(PROMISE_MESSAGE_EXPECTATION_TIMED);
 	const { signal, time } = createPromiseOptions(options);
-	if (signal?.aborted ?? false) return Promise.reject(signal?.reason);
+	if (signal?.aborted ?? false) throw signal?.reason;
 	return time > 0 ? getTimedPromise(promise, time, signal) : promise;
 }
 //#endregion
 //#region src/promise/index.ts
 async function attemptPromise(value, options) {
 	const isFunction = typeof value === "function";
-	if (!isFunction && !(value instanceof Promise)) return Promise.reject(/* @__PURE__ */ new TypeError(PROMISE_MESSAGE_EXPECTATION_ATTEMPT));
+	if (!isFunction && !(value instanceof Promise)) throw new TypeError(PROMISE_MESSAGE_EXPECTATION_ATTEMPT);
 	const { signal, time } = createPromiseOptions(options);
-	if (signal?.aborted ?? false) return Promise.reject(signal?.reason);
+	if (signal?.aborted ?? false) throw signal?.reason;
 	const aborter = createAborter(signal, () => {
 		rejector(signal?.reason);
 	});
@@ -3378,8 +3601,8 @@ async function attemptPromise(value, options) {
 }
 async function promises(items, options) {
 	const { signal, strategy } = createPromisesOptions(options);
-	if (signal?.aborted ?? false) return Promise.reject(signal?.reason);
-	if (!isArrayOrPlainObject(items)) return Promise.reject(PROMISE_MESSAGE_EXPECTATION_ITEMS_TYPE);
+	if (signal?.aborted ?? false) throw signal?.reason;
+	if (!isArrayOrPlainObject(items)) throw new TypeError(PROMISE_MESSAGE_EXPECTATION_ITEMS_TYPE);
 	const isArray = Array.isArray(items);
 	const actual = (isArray ? items.map((item, index) => [index, item]) : Object.entries(items)).map(([key, value]) => [key, typeof value === "function" ? value() : value]).filter(([, value]) => value instanceof Promise);
 	const aborter = createAborter(signal, () => {
@@ -3442,10 +3665,10 @@ function handleResult$1(result, first, second) {
 		error = second;
 	}
 	if (isOk(result)) {
-		if (typeof ok !== "function") throw new Error(MATCH_MESSAGE_OK);
+		if (typeof ok !== "function") throw new TypeError(MATCH_MESSAGE_OK);
 		return ok(result.value);
 	}
-	if (typeof error !== "function") throw new Error(MATCH_MESSAGE_ERROR);
+	if (typeof error !== "function") throw new TypeError(MATCH_MESSAGE_ERROR);
 	return error(result.error, result.original);
 }
 function matchResult(result, first, second) {
@@ -3483,9 +3706,11 @@ attemptFlow.async = attemptAsyncFlow;
 //#endregion
 //#region src/result/work/pipe.ts
 async function attemptAsyncPipe(initial, first, ...seconds) {
-	return asyncAttempt(() => {
+	return asyncAttempt(async () => {
 		if (isError(initial)) throw initial.error;
-		const value = typeof initial === "function" ? initial() : isOk(initial) ? initial.value : initial;
+		let value;
+		if (typeof initial === "function") value = initial();
+		else value = isOk(initial) ? initial.value : initial;
 		if (first == null) return value;
 		return asyncPipe(value, ...[first, ...seconds]);
 	});
@@ -3493,7 +3718,9 @@ async function attemptAsyncPipe(initial, first, ...seconds) {
 function attemptPipe(initial, first, ...seconds) {
 	return attempt(() => {
 		if (isError(initial)) throw initial.error;
-		const value = typeof initial === "function" ? initial() : isOk(initial) ? initial.value : initial;
+		let value;
+		if (typeof initial === "function") value = initial();
+		else value = isOk(initial) ? initial.value : initial;
 		if (first == null) return value;
 		return pipe(value, ...[first, ...seconds]);
 	});
@@ -3514,6 +3741,14 @@ const FUZZY_SYMBOL = Symbol(FUZZY_PROPERTY);
 * @param needle String to look for
 * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
 * @returns `true` if the string ends with the given substring, otherwise `false`
+*
+* @example
+* ```typescript
+* endsWith('this is a test', 'test');          // => true
+* endsWith('this is a test', 'Test');          // => false
+* endsWith('this is a test', 'Test', true);    // => true
+* endsWith('this is a test', 'not');           // => false
+* ```
 */
 function endsWith(haystack, needle, ignoreCase) {
 	return match(STRING_MATCH_ENDS_WITH, haystack, needle, ignoreCase === true);
@@ -3525,6 +3760,14 @@ function endsWith(haystack, needle, ignoreCase) {
 * @param needle String to look for
 * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
 * @returns `true` if the string includes the given substring, otherwise `false`
+*
+* @example
+* ```typescript
+* includes('this is a test', 'is');          // => true
+* includes('this is a test', 'Is');          // => false
+* includes('this is a test', 'Is', true);    // => true
+* includes('this is a test', 'not');         // => false
+* ```
 */
 function includes(haystack, needle, ignoreCase) {
 	return match(STRING_MATCH_INCLUDES, haystack, needle, ignoreCase === true);
@@ -3544,6 +3787,14 @@ function matchCallback(haystack, needle, ignoreCase) {
 * @param needle String to look for
 * @param ignoreCase Ignore case when matching? _(defaults to `false`)_
 * @returns `true` if the string starts with the given substring, otherwise `false`
+*
+* @example
+* ```typescript
+* startsWith('this is a test', 'this');          // => true
+* startsWith('this is a test', 'This');          // => false
+* startsWith('this is a test', 'This', true);    // => true
+* startsWith('this is a test', 'not');           // => false
+* ```
 */
 function startsWith(haystack, needle, ignoreCase) {
 	return match(STRING_MATCH_STARTS_WITH, haystack, needle, ignoreCase === true);
@@ -3568,7 +3819,7 @@ Object.defineProperties(Fuzzy.prototype, {
 	}
 });
 function createFuzzyItems(items) {
-	return items.sort((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
+	return items.toSorted((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
 }
 function createFuzzyOptions(input, state) {
 	const options = isPlainObject(input) ? input : {};
@@ -3751,7 +4002,7 @@ function dedent(value, ...values) {
 	}
 	if (lengths.length === 0) return actual.trim();
 	const minimum = min(lengths);
-	const pattern = new RegExp(`^\\s{0,${minimum}}`);
+	const pattern = new RegExp(String.raw`^\s{0,${minimum}}`);
 	let result = "";
 	for (let index = 0; index < length; index += 1) {
 		const line = lines[index];
@@ -3788,7 +4039,7 @@ function getUuid(html) {
 *
 * @param value JSON string to parse
 * @param reviver Reviver function to transform the parsed values
-* @returns Parsed value or `undefined` if parsing fails
+* @returns Parsed value, or `undefined` if parsing fails
 */
 function parse(value, reviver) {
 	try {
@@ -3802,6 +4053,13 @@ function parse(value, reviver) {
 *
 * @param value String to trim
 * @returns Trimmed string
+* @example
+* ```typescript
+* trim('  this is a test  '); // => 'this is a test'
+* trim('this is a test');     // => 'this is a test'
+* trim('   ');                // => ''
+* trim('');                   // => ''
+* ```
 */
 function trim(value) {
 	return typeof value === "string" ? value.trim() : "";
@@ -3813,6 +4071,13 @@ function trim(value) {
 * @param length Maximum length of the string after truncation
 * @param suffix Suffix to append to the truncated string
 * @returns Truncated string
+* @example
+* ```typescript
+* truncate('this is a test', 7);          // => 'this is'
+* truncate('this is a test', 7, '...');   // => 'this ...'
+* truncate('this is a test', 20);         // => 'this is a test'
+* truncate('this is a test', 0);          // => ''
+* ```
 */
 function truncate(value, length, suffix) {
 	if (typeof value !== "string" || typeof length !== "number" || length === 0) return "";
@@ -4020,7 +4285,7 @@ function clone(value, options) {
 function cloneAny(value, parameters, depth, options) {
 	switch (true) {
 		case value === null || CLONE_PRIMITIVES[typeof value]: return value;
-		case value instanceof Date: return new Date(value.getTime());
+		case value instanceof Date: return new Date(value);
 		case typeof value === "function":
 			parameters.options ??= createCloneOptions(options);
 			return parameters.options.copyFunctions ? value : void 0;
@@ -4384,7 +4649,9 @@ freeze.is = isFrozen;
 //#region src/internal/value/partial.ts
 function partial(value, providedKeys, omit) {
 	if (!isPlainObject(value)) return {};
-	const keys = omit ? Object.keys(value) : Array.isArray(providedKeys) ? providedKeys : [];
+	let keys;
+	if (omit) keys = Object.keys(value);
+	else keys = Array.isArray(providedKeys) ? providedKeys : [];
 	const { length } = keys;
 	if (length === 0) return omit ? value : {};
 	const partials = {};
@@ -4557,6 +4824,12 @@ function createMergingOptions(input) {
 	actual.skipNullableInArrays = options.skipNullableInArrays === true;
 	return actual;
 }
+function getFullKey(prefix, key, options) {
+	let full;
+	if (options.replaceableObjects == null) full = void 0;
+	else full = prefix == null ? key : `${prefix}.${key}`;
+	return full;
+}
 function getReplaceableObjects(value) {
 	const items = (Array.isArray(value) ? value : [value]).filter((item) => typeof item === "string" || item instanceof RegExp);
 	if (items.length === 0) return;
@@ -4584,6 +4857,9 @@ function initializeAssigner(options) {
 function initializeMerger(options) {
 	return new Merger(createMergingOptions(options));
 }
+function isMergeable(next, previous, options, full) {
+	return isArrayOrPlainObject(next) && isArrayOrPlainObject(previous) && !(options.replaceableObjects?.(full) ?? false);
+}
 /**
 * Merge multiple arrays or objects into a single one
 *
@@ -4610,9 +4886,9 @@ function mergeObjects(values, options, destination, prefix) {
 			const key = keys[innerIndex];
 			const next = item[key];
 			const previous = merged[key];
-			if (next == null && (options.skipNullableAny || isArray && options.skipNullableInArrays)) continue;
-			const full = options.replaceableObjects == null ? void 0 : prefix == null ? key : `${prefix}.${key}`;
-			if (isArrayOrPlainObject(next) && isArrayOrPlainObject(previous) && !(options.replaceableObjects?.(full) ?? false)) merged[key] = mergeObjects([previous, next], options, destination == null ? void 0 : merged[key], full);
+			if (skipMerge(next, options, isArray)) continue;
+			const fullKey = getFullKey(prefix, key, options);
+			if (isMergeable(next, previous, options, fullKey)) merged[key] = mergeObjects([previous, next], options, destination == null ? void 0 : merged[key], fullKey);
 			else merged[key] = next;
 		}
 	}
@@ -4624,7 +4900,11 @@ function mergeValues(values, options, prefix) {
 	if (actual.length === 0) return {};
 	if (options.assignValues && actual.length === 2 && !Array.isArray(actual[0]) && Object.keys(actual[0]).length === 0) return Object.assign(actual[0], actual[1]);
 	if (actual.length > 1) return mergeObjects(actual, options, options.assignValues ? actual[0] : void 0, prefix);
-	return options.assignValues ? actual[0] : Array.isArray(actual[0]) ? actual[0].slice() : { ...actual[0] };
+	if (options.assignValues) return actual[0];
+	return Array.isArray(actual[0]) ? actual[0].slice() : { ...actual[0] };
+}
+function skipMerge(next, options, isArray) {
+	return next == null && (options.skipNullableAny || isArray && options.skipNullableInArrays);
 }
 assign.initialize = initializeAssigner;
 merge.initialize = initializeMerger;
@@ -4805,7 +5085,7 @@ function createSubscriptionsProperty(input) {
 	const values = isPlainObject(input) ? input : {};
 	return {
 		key: typeof values.key === "string" ? values.key : SUBSCRIPTION_PROPERTY,
-		value: values.value == null ? SUBSCRIPTION_NAME : values.value
+		value: values.value ?? "subscription"
 	};
 }
 function createSubscriptionsState(property, keys) {
@@ -5340,7 +5620,8 @@ function setColorAlpha(value) {
 //#endregion
 //#region src/color/misc/get.ts
 function getClampedValue(value, minimum, maximum, rounding) {
-	return typeof value === "number" && !Number.isNaN(value) ? clamp(rounding ?? false ? round(value) : value, minimum, maximum) : minimum;
+	if (typeof value !== "number" || Number.isNaN(value)) return minimum;
+	return clamp(rounding ?? false ? round(value) : value, minimum, maximum);
 }
 function getForegroundColor(value, hex) {
 	const { blue, green, red } = getColorFromState(getColorState(value), COLOR_TYPE.rgb);
@@ -5846,9 +6127,17 @@ function getHexaColor$1() {
 * @param value Value to normalize
 * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
 * @returns Normalized hex color
+*
+* @example
+* ```typescript
+* getNormalizedHex('#abc'); // => '#aabbcc'
+* getNormalizedHex('#abc', true); // => '#aabbccff'
+* getNormalizedHex(123); // => '#000000'
+* getNormalizedHex(123, true); // => '#000000ff'
+* ```
 */
 function getNormalizedHex(value, alpha) {
-	const includeAlpha = alpha ?? false;
+	const includeAlpha = alpha === true;
 	if (!isHexColor(value)) return `${COLOR_DEFAULTS.hexBlack}${includeAlpha ? COLOR_ALPHA.fullHexLong : ""}`;
 	const normalized = value.replace(COLOR_EXPRESSION.prefix, "");
 	if (normalized.length < COLOR_LENGTHS.hexLong) return join(`${normalized.slice(0, COLOR_LENGTHS.hexShort)}${includeAlpha ? normalized[COLOR_LENGTHS.hexShort] ?? COLOR_ALPHA.fullHexShort : ""}`.split("").map((character) => character.repeat(2)));
@@ -6620,12 +6909,24 @@ function getTimeLoggerStop() {
 	}
 	return noop;
 }
+/**
+* Is the value a _Logger_?
+*
+* @param value Value to check
+* @returns `true` if the value is a _Logger_, otherwise `false`
+*/
 function isLogger(value) {
 	return isLoggerInstance(LOGGER_NAME, value);
 }
 function isLoggerInstance(name, value) {
 	return typeof value === "object" && value !== null && "$logger" in value && value["$logger"] === name;
 }
+/**
+* Is the value a _TimeLogger_?
+*
+* @param value Value to check
+* @returns `true` if the value is a _TimeLogger_, otherwise `false`
+*/
 function isTimeLogger(value) {
 	return isLoggerInstance(LOGGER_NAME_TIMED, value);
 }
@@ -6651,6 +6952,13 @@ function average(array, key) {
 * @param value Number to round up
 * @param decimals Number of decimal places to round to _(defaults to `0`)_
 * @returns Rounded number, or `Number.NaN` if the value if unable to be rounded
+*
+* @example
+* ```typescript
+* ceil(1.234, 2); // => 1.24
+* ceil(1.234);    // => 2
+* ceil('abc');    // => Number.NaN
+* ```
 */
 function ceil(value, decimals) {
 	return roundNumber(Math.ceil, value, decimals);
@@ -7128,14 +7436,13 @@ async function run$1(state) {
 	state.runners += 1;
 	let item = state.items.shift();
 	while (item != null) {
+		const next = item;
 		let error = false;
 		let result;
 		const attempted = await asyncAttempt(async () => {
-			if (item != null && !(item.aborter?.signal?.aborted ?? false)) {
-				const parameters = item.key == null ? item.parameters : [item.key, ...item.parameters];
-				return await state.callback(...parameters);
-			}
-			throw new Error();
+			if (next.aborter?.signal?.aborted) throw next.aborter.signal.reason;
+			const parameters = next.key == null ? next.parameters : [next.key, ...next.parameters];
+			return await state.callback(...parameters);
 		});
 		if (attempted.ok) result = attempted.value;
 		else {
@@ -7166,7 +7473,7 @@ const RANDOM_HEX_CHARACTERS = "0123456789ABCDEF";
 * @returns Random boolean
 */
 function getRandomBoolean() {
-	return Math.random() > RANDOM_BOOLEAN_MODIFIER;
+	return getRandom() > RANDOM_BOOLEAN_MODIFIER;
 }
 /**
 * Get a random string of characters with a specified length
@@ -7271,4 +7578,4 @@ var SizedSet = class extends Set {
 	}
 };
 //#endregion
-export { CancelablePromise, Logger, PromiseTimeoutError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, push as append, push, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assertProperty, assign, asyncAttempt, asyncAttemptRun, asyncDebounce, asyncFail, asyncFlow, asyncMatchResult, asyncOnce, asyncPipe, asyncRun, asyncSucceed, asyncThrottle, asyncUse, attempt, attemptAsyncFlow, attemptAsyncPipe, attemptFlow, attemptPipe, attemptPromise, attemptRun, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, copy, count, debounce, deburr, dedent, delay, deregisterCloner, deregisterComparator, deregisterEqualizer, diff, difference, drop, endsWith, endsWithArray, equal, error, exclude, exists, fail, filter, filterAndMap, filterAndMap as select, find, findLast, first, firstOrDefault, flatFreeze, flatten, floor, flow, freeze, fromQuery, toPromise as fromResult, toPromise, fuzzy, fuzzyMatch, getArray, getArrayComparison, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getHwbColor, getHwbaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloatingNumber as getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getSortedIndex, getString, getTimedPromise, getUuid, getValue, groupArraysBy, groupBy, handleResult, hasValue, hasValueResult, herald, hexToHsl, hexToHsla, hexToHwb, hexToHwba, hexToRgb, hexToRgba, hslToHex, hslToHwb, hslToHwba, hslToRgb, hslToRgba, hwbToHex, hwbToHsl, hwbToHsla, hwbToRgb, hwbToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, initializeAssigner, initializeCloner, initializeEqualizer, initializeMerger, initializeNormalizer, initializeSorter, initializeTemplater, initializeTransformer, insert, interpolate, intersection, isArrayOrPlainObject, isAsyncFailure, isAsyncGenerator, isAsyncGeneratorFunction, isAsyncOnce, isAsyncPlan, isAsyncStep, isAsyncSuccess, isBeacon, isBeaconSubscription, isColor, isConstructor, isEmpty, isError, isFailure, isFrozen, isFulfilled, isFuzzy, isGenerator, isGeneratorFunction, isHerald, isHeraldEvents, isHeraldSubscription, isHexColor, isHslColor, isHslaColor, isHwbColor, isHwbaColor, isInstanceOf, isKey, isKeyedQueue, isLogger, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTemplateStringsArray, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isObservable, isOk, isOnce, isPlainObject, isPlan, isPrimitive, isQueue, isQueueInstance, isRejected, isResult, isRgbColor, isRgbaColor, isSorted, isStep, isSubscription, isSubscriptions, isSuccess, isTemplateStringsArray, isTimeLogger, isTypedArray, join, kebabCase, keyedQueue, last, lastIndexOf, lastOrDefault, lowerCase, mapAndFilter, mapAndFilter as reverseSelect, matchResult, max, median, memoize, merge, min, move, moveIndices, moveToIndex, noop, normalize, ok, omit, once, parse, partition, pascalCase, pick, pipe, plan, promises, queue, range, registerCloner, registerComparator, registerEqualizer, resultPromises, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, rgbToHwb, rgbToHwba, round, run, setValue, settlePromise, shake, shuffle, single, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, subscriptions, succeed, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toMapArrays, toQuery, toRecord, toRecordArrays, toResult, toSet, toggle, transform, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, use, words };
+export { CancelablePromise, Logger, PromiseTimeoutError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, push as append, push, assert, assertCondition, assertDefined, assertInstanceOf, assertIs, assertProperty, assign, asyncAttempt, asyncAttemptRun, asyncDebounce, asyncFail, asyncFlow, asyncMatchResult, asyncOnce, asyncPipe, asyncRun, asyncSucceed, asyncThrottle, asyncUse, attempt, attemptAsyncFlow, attemptAsyncPipe, attemptFlow, attemptPipe, attemptPromise, attemptRun, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, copy, count, debounce, deburr, dedent, delay, deregisterCloner, deregisterComparator, deregisterEqualizer, diff, difference, drop, endsWith, endsWithArray, equal, error, exclude, exists, fail, filter, filterAndFlatMap, filterAndMap, filterAndMap as select, find, findLast, first, firstOrDefault, flatFreeze, flatMapAndFilter, flatten, floor, flow, freeze, fromQuery, toPromise as fromResult, toPromise, fuzzy, fuzzyMatch, getArray, getArrayComparison, getColor, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getHwbColor, getHwbaColor, getNormalizedHex, getNumber, getRandom, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloatingNumber as getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getSortedIndex, getString, getTimedPromise, getUuid, getValue, groupArraysBy, groupBy, handleResult, hasValue, hasValueResult, herald, hexToHsl, hexToHsla, hexToHwb, hexToHwba, hexToRgb, hexToRgba, hslToHex, hslToHwb, hslToHwba, hslToRgb, hslToRgba, hwbToHex, hwbToHsl, hwbToHsla, hwbToRgb, hwbToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, initializeAssigner, initializeCloner, initializeEqualizer, initializeMerger, initializeNormalizer, initializeSorter, initializeTemplater, initializeTransformer, insert, interpolate, intersection, isArrayOrPlainObject, isAsyncFailure, isAsyncGenerator, isAsyncGeneratorFunction, isAsyncOnce, isAsyncPlan, isAsyncStep, isAsyncSuccess, isBeacon, isBeaconSubscription, isColor, isConstructor, isEmpty, isError, isFailure, isFrozen, isFulfilled, isFuzzy, isGenerator, isGeneratorFunction, isHerald, isHeraldEvents, isHeraldSubscription, isHexColor, isHslColor, isHslaColor, isHwbColor, isHwbaColor, isInstanceOf, isKey, isKeyedQueue, isLogger, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTemplateStringsArray, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isObservable, isOk, isOnce, isPlainObject, isPlan, isPrimitive, isQueue, isRejected, isResult, isRgbColor, isRgbaColor, isSorted, isStep, isSubscription, isSubscriptions, isSuccess, isTemplateStringsArray, isTimeLogger, isTypedArray, join, kebabCase, keyedQueue, last, lastIndexOf, lastOrDefault, lowerCase, mapAndFilter, mapAndFilter as reverseSelect, matchResult, max, median, memoize, merge, min, move, moveIndices, moveToIndex, noop, normalize, ok, omit, once, parse, partition, pascalCase, pick, pipe, plan, promises, queue, range, registerCloner, registerComparator, registerEqualizer, resultPromises, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, rgbToHwb, rgbToHwba, round, run, setValue, settlePromise, shake, shuffle, single, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, subscriptions, succeed, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toMapArrays, toQuery, toRecord, toRecordArrays, toResult, toSet, toggle, transform, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, use, words };