@oscarpalmer/atoms 0.218.0 → 0.219.0

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,24 +18,27 @@ 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, keyCallback, length, mapAfter, mapBefore, result, type, value } = parameters;
+	const { array, arrayLength, callback, limit, result, type, value } = parameters;
 	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 = keyCallback?.(item, index, array) ?? item;
-			transformed = item;
-		} else {
-			transformed = mapBefore(item, index, array);
-			keyed = keyCallback?.(transformed, index, array) ?? transformed;
-		}
+	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(mapAfter?.(item, index, array) ?? transformed);
-		} else result.notMatched.push(item);
+			result.matched.push(mapped);
+			if (result.matched.length >= limit) return result;
+		} else result.notMatched.push(arrayItem);
 	}
 	return result;
 }
@@ -34,13 +46,28 @@ 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(array, length, value, boolCallback, mapBefore, mapAfter, result) {
-	const callback = boolCallback ?? ((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);
+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;
 }
@@ -64,50 +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);
-	if (index === -1) return useDefaultValue ? defaultValue : void 0;
-	return array[index];
-}
-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;
-	let mapAfter;
-	let mapBefore;
-	if (mapCallback == null) {
-		mapAfter = void 0;
-		mapBefore = void 0;
-	} else {
-		mapAfter = mapReverse ? void 0 : mapCallback;
-		mapBefore = mapReverse ? mapCallback : void 0;
-	}
-	if (callbacks?.bool != null || type === "all" && key == null) return findSimpleValues(array, length, value, callbacks?.bool, mapBefore, mapAfter, result);
-	return findComplexValues({
+	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,
-		length,
-		mapAfter,
-		mapBefore,
+		arrayLength,
+		flat,
+		limit,
+		map,
 		result,
 		type,
 		value,
-		keyCallback: callbacks?.keyed
-	});
+		callback: simple ? callbacks?.bool : callbacks?.keyed
+	};
+	return simple ? findSimpleValues(findParameters) : findComplexValues(findParameters);
 }
 //#endregion
 export { createFindParameters, findAbsoluteValueOrDefault, findValue, findValues };

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/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

@@ -6,6 +6,13 @@
  * @param minimum Minimum 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

@@ -9,6 +9,13 @@ import { EXPRESSION_NUMBER_BINARY, EXPRESSION_NUMBER_OCTAL, EXPRESSION_NUMBER_ZE
 * @param minimum Minimum 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 (![
@@ -51,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/string/case.d.mts

@@ -4,6 +4,14 @@
  *
  * @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'
+ * ```
  */
 export declare function camelCase(value: string): string;
 /**
@@ -11,6 +19,14 @@ export declare function camelCase(value: string): string;
  *
  * @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('');               // => ''
+ * ```
  */
 export declare function capitalize(value: string): string;
 /**
@@ -18,6 +34,14 @@ export declare function capitalize(value: string): string;
  *
  * @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'
+ * ```
  */
 export declare function kebabCase(value: string): string;
 /**
@@ -25,6 +49,13 @@ export declare function kebabCase(value: string): string;
  *
  * @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'
+ * ```
  */
 export declare function lowerCase(value: string): string;
 /**
@@ -32,6 +63,14 @@ export declare function lowerCase(value: string): string;
  *
  * @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'
+ * ```
  */
 export declare function pascalCase(value: string): string;
 /**
@@ -39,6 +78,14 @@ export declare function pascalCase(value: string): string;
  *
  * @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'
+ * ```
  */
 export declare function snakeCase(value: string): string;
 /**
@@ -46,6 +93,14 @@ export declare function snakeCase(value: string): string;
  *
  * @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('');               // => ''
+ * ```
  */
 export declare function titleCase(value: string): string;
 /**
@@ -53,6 +108,14 @@ export declare function titleCase(value: string): string;
  *
  * @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('');               // => ''
+ * ```
  */
 export declare function upperCase(value: string): string;
 //#endregion