@oscarpalmer/atoms 0.217.0 → 0.219.0

package/dist/internal/array/callbacks.mjs

@@ -3,7 +3,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;
 	}
 }

package/dist/internal/array/find.d.mts

@@ -1,8 +1,8 @@
-import { ArrayFindMapper, ArrayFindValueType, ArrayFindValuesResult, ArrayFindValuesType, ArrayParameters } from "../../models/array/array.find.model.mjs";
+import { ArrayFindOptions, ArrayFindValueType, ArrayFindValuesResult, ArrayFindValuesType, ArrayParameters } from "../../models/array/array.find.model.mjs";
 //#region src/internal/array/find.d.ts
 export declare function createFindParameters(original: unknown[]): ArrayParameters;
+export declare function findAbsoluteValueOrDefault(array: unknown[], parameters: unknown[], defaultValue: unknown, useDefaultValue: boolean, reversed: boolean): unknown;
 export declare function findValue(type: Exclude<ArrayFindValueType, "item">, array: unknown[], parameters: unknown[], reversed: boolean): number;
 export declare function findValue(type: Exclude<ArrayFindValueType, "index">, array: unknown[], parameters: unknown[], reversed: boolean): unknown;
-export declare function findAbsoluteValueOrDefault(array: unknown[], parameters: unknown[], defaultValue: unknown, useDefaultValue: boolean, reversed: boolean): unknown;
-export declare function findValues(type: ArrayFindValuesType, array: unknown[], parameters: unknown[], mapper?: ArrayFindMapper): ArrayFindValuesResult;
+export declare function findValues(type: ArrayFindValuesType, array: unknown[], parameters: unknown[], options?: ArrayFindOptions): ArrayFindValuesResult;
 //#endregion

package/dist/internal/array/find.mjs

@@ -1,6 +1,15 @@
 import { ARRAY_FIND_VALUE_INDEX } from "../../models/array/array.find.model.mjs";
 import { getArrayCallback, getArrayCallbacks } from "./callbacks.mjs";
 //#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 {
@@ -9,15 +18,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];
@@ -32,59 +91,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
 export { createFindParameters, findAbsoluteValueOrDefault, findValue, findValues };

package/dist/internal/array/insert.mjs

@@ -3,7 +3,7 @@ import { chunk } from "./chunk.mjs";
 import { max, min } from "../math/aggregate.mjs";
 //#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;

package/dist/internal/array/match.mjs

@@ -4,6 +4,21 @@ import { ARRAY_MATCH_COMPARISON_INSIDE, ARRAY_MATCH_COMPARISON_SAME, ARRAY_MATCH
 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];
 }
@@ -17,23 +32,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]);

package/dist/internal/array/sets.mjs

@@ -6,8 +6,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;

package/dist/internal/array/shuffle.d.mts

@@ -4,6 +4,11 @@
  *
  * @param array Original array
  * @returns Shuffled array
+ *
+ * @example
+ * ```typescript
+ * shuffle([1, 2, 3]); // => [3, 1, 2] (maybe? it's random, you know)
+ * ```
  */
 export declare function shuffle<Item>(array: Item[]): Item[];
 //#endregion

package/dist/internal/array/shuffle.mjs

@@ -5,6 +5,11 @@ import { getRandomInteger } from "../random.mjs";
 *
 * @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 [];

package/dist/internal/math/aggregate.d.mts

@@ -7,6 +7,11 @@ export declare function getAggregated(type: NonAverageAggregationType, array: un
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param callback Callback to get an item's value
+ * @param first Return only the first item with the maximum value
+ * @returns Item with the maximum value, or `undefined` if no maximum can be found
+ *
  * @example
  * ```typescript
  * max(
@@ -16,16 +21,16 @@ export declare function getAggregated(type: NonAverageAggregationType, array: un
  *
  * max([], item => item.value); // => []
  * ```
- *
- * @param items List of items
- * @param callback Callback to get an item's value
- * @param first Return only the first item with the maximum value
- * @returns Item with the maximum value, or `undefined` if no maximum can be found
  */
 export declare function max<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number, first: true): Item | undefined;
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param key Key to use for value
+ * @param first Return only the first item with the maximum value
+ * @returns Item with the maximum value, or `undefined` if no maximum can be found
+ *
  * @example
  * ```typescript
  * max(
@@ -35,16 +40,15 @@ export declare function max<Item>(items: Item[], callback: (item: Item, index: n
  *
  * max([], 'value'); // => []
  * ```
- *
- * @param items List of items
- * @param key Key to use for value
- * @param first Return only the first item with the maximum value
- * @returns Item with the maximum value, or `undefined` if no maximum can be found
  */
 export declare function max<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>, first: true): Item | undefined;
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param callback Callback to get an item's value
+ * @returns Items with the maximum value
+ *
  * @example
  * ```typescript
  * max(
@@ -54,15 +58,15 @@ export declare function max<Item extends PlainObject>(items: Item[], key: keyof
  *
  * max([], item => item.value); // => []
  * ```
- *
- * @param items List of items
- * @param callback Callback to get an item's value
- * @returns Items with the maximum value
  */
 export declare function max<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): Item[];
 /**
  * Get the maximum value from a list of items
  *
+ * @param items List of items
+ * @param key Key to use for value
+ * @returns Items with the maximum value
+ *
  * @example
  * ```typescript
  * max(
@@ -72,23 +76,19 @@ export declare function max<Item>(items: Item[], callback: (item: Item, index: n
  *
  * max([], 'value'); // => []
  * ```
- *
- * @param items List of items
- * @param key Key to use for value
- * @returns Items with the maximum value
  */
 export declare function max<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): Item[];
 /**
  * Get the maximum value from a list of numbers
  *
+ * @param values List of numbers
+ * @returns Maximum value, or `Number.NaN` if no maximum can be found
+ *
  * @example
  * ```typescript
  * max([10, 20]); // => 20
  * max([]);       // => Number.NaN
  * ```
- *
- * @param values List of numbers
- * @returns Maximum value, or `Number.NaN` if no maximum can be found
  */
 export declare function max(values: number[]): number;
 /**
@@ -98,6 +98,17 @@ export declare function max(values: number[]): number;
  * @param callback Callback to get an item's value
  * @param first Return only the first item with the minimum value
  * @returns First item with the minimum value, or `undefined` if no minimum can be found
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   item => item.value,
+ *   true,
+ * ); // => {id: 2, value: 5}
+ *
+ * min([], item => item.value, true); // => undefined
+ * ```
  */
 export declare function min<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number, first: true): Item | undefined;
 /**
@@ -107,6 +118,17 @@ export declare function min<Item>(items: Item[], callback: (item: Item, index: n
  * @param key Key to use for value
  * @param first Return only the first item with the minimum value
  * @returns First item with the minimum value, or `undefined` if no minimum can be found
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   'value',
+ *   true,
+ * ); // => {id: 2, value: 5}
+ *
+ * min([], 'value', true); // => undefined
+ * ```
  */
 export declare function min<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>, first: true): Item | undefined;
 /**
@@ -115,6 +137,16 @@ export declare function min<Item extends PlainObject>(items: Item[], key: keyof
  * @param items List of items
  * @param callback Callback to get an item's value
  * @returns Items with the minimum value
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   item => item.value,
+ * ); // => [{id: 2, value: 5}]
+ *
+ * min([], item => item.value); // => []
+ * ```
  */
 export declare function min<Item>(items: Item[], callback: (item: Item, index: number, array: Item[]) => number): Item[];
 /**
@@ -123,6 +155,16 @@ export declare function min<Item>(items: Item[], callback: (item: Item, index: n
  * @param items List of items
  * @param key Key to use for value
  * @returns Items with the minimum value
+ *
+ * @example
+ * ```typescript
+ * min(
+ *   [{id: 1, value: 10}, {id: 2, value: 5}],
+ *   'value',
+ * ); // => [{id: 2, value: 5}]
+ *
+ * min([], 'value'); // => []
+ * ```
  */
 export declare function min<Item extends PlainObject>(items: Item[], key: keyof NumericalValues<Item>): Item[];
 /**
@@ -130,6 +172,12 @@ export declare function min<Item extends PlainObject>(items: Item[], key: keyof
  *
  * @param values List of numbers
  * @returns Minimum value, or `Number.NaN` if no minimum can be found
+ *
+ * @example
+ * ```typescript
+ * min([10, 20]); // => 10
+ * min([]);       // => Number.NaN
+ * ```
  */
 export declare function min(values: number[]): number;
 //#endregion

package/dist/internal/math/aggregate.mjs

@@ -44,7 +44,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;

package/dist/internal/math/misc.d.mts

@@ -5,6 +5,13 @@
  * @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
+ * ```
  */
 export declare function floor(value: number, decimals?: number): number;
 /**
@@ -13,6 +20,13 @@ export declare function floor(value: number, decimals?: number): number;
  * @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
+ * ```
  */
 export declare function round(value: number, decimals?: number): number;
 export declare function roundNumber(callback: (value: number) => number, value: number, decimals?: number): number;

package/dist/internal/math/misc.mjs

@@ -5,6 +5,13 @@
 * @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);
@@ -15,6 +22,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);

package/dist/internal/number.d.mts

@@ -4,8 +4,15 @@
  *
  * @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
+ * ```
  */
 export declare function between(value: number, minimum: number, maximum: number): boolean;
 /**
@@ -31,6 +38,17 @@ export declare function clamp(value: number, minimum: number, maximum: number, l
  *
  * @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
+ * ```
  */
 export declare function getNumber(value: unknown): number;
 //#endregion

package/dist/internal/number.mjs

@@ -1,4 +1,5 @@
 import { isNumber } from "./is.mjs";
+import { max, min } from "./math/aggregate.mjs";
 import { EXPRESSION_NUMBER_BINARY, EXPRESSION_NUMBER_OCTAL, EXPRESSION_NUMBER_ZEROISH } from "../models/misc.model.mjs";
 //#region src/internal/number.ts
 /**
@@ -6,8 +7,15 @@ import { EXPRESSION_NUMBER_BINARY, EXPRESSION_NUMBER_OCTAL, EXPRESSION_NUMBER_ZE
 *
 * @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 (![
@@ -16,7 +24,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
@@ -49,6 +58,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;

package/dist/internal/plan/plan.generate.mjs

@@ -4,7 +4,7 @@ import { isError, isOk } from "../result/misc.mjs";
 //#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);
@@ -13,7 +13,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;
@@ -29,7 +29,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;
 }