@oscarpalmer/atoms 0.176.0 → 0.177.0

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.176.0",
+	"version": "0.177.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -37,10 +37,18 @@
 			"types": "./dist/array/filter.d.mts",
 			"default": "./dist/array/filter.mjs"
 		},
+		"./array/first": {
+			"types": "./dist/array/first.d.mts",
+			"default": "./dist/array/first.mjs"
+		},
 		"./array/group-by": {
 			"types": "./dist/array/group-by.d.mts",
 			"default": "./dist/array/group-by.mjs"
 		},
+		"./array/last": {
+			"types": "./dist/array/last.d.mts",
+			"default": "./dist/array/last.mjs"
+		},
 		"./array/move": {
 			"types": "./dist/array/move.d.mts",
 			"default": "./dist/array/move.mjs"
@@ -245,4 +253,4 @@
 		"vitest": "npm:@voidzero-dev/vite-plus-test@latest"
 	},
 	"packageManager": "npm@11.11.1"
-}
+}

package/plugin/index.js

@@ -15,10 +15,11 @@ export const arrayPlugins = [
 	getPlugin('array', 'slice', new Set(['slice'])),
 	getPlugin('array', 'sort', new Set(['sort'])),
 	getPlugin('array', 'splice', new Set(['splice'])),
-	getPlugin('array', 'times', new Set(['from']), true),
+	// getPlugin('array', 'times', new Set(['from']), true),
 ];
 
 export const mathPlugins = [
+	getPlugin('math', 'ceil', new Set(['ceil']), true),
 	getPlugin('math', 'floor', new Set(['floor']), true),
 	getPlugin('math', 'max', new Set(['max']), true),
 	getPlugin('math', 'min', new Set(['min']), true),

package/src/array/exists.ts

@@ -52,7 +52,7 @@ export function exists(array: unknown[], ...parameters: unknown[]): boolean {
 		return Array.isArray(array) ? array.includes(parameters[0]) : false;
 	}
 
-	return (findValue(FIND_VALUE_INDEX, array, parameters) as number) > -1;
+	return (findValue(FIND_VALUE_INDEX, array, parameters, false) as number) > -1;
 }
 
 // #endregion

package/src/array/filter.ts

@@ -53,22 +53,48 @@ export function filter(array: unknown[], ...parameters: unknown[]): unknown[] {
 
 filter.remove = removeFiltered;
 
+/**
+ * Get a filtered array of items that do not match the filter
+ * @param array Array to search in
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns Filtered array of items that do not match the filter
+ */
 function removeFiltered<
 	Item,
 	Callback extends (item: Item, index: number, array: Item[]) => unknown,
 >(array: Item[], callback: Callback, value: ReturnType<Callback>): unknown[];
 
+/**
+ * Get a filtered array of items that do not match the filter
+ * @param array Array to search in
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns Filtered array of items that do not match the filter
+ */
 function removeFiltered<Item extends PlainObject, ItemKey extends keyof Item>(
 	array: Item[],
 	key: ItemKey,
 	value: Item[ItemKey],
 ): unknown[];
 
+/**
+ * Get a filtered array of items that do not match the filter
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @returns Filtered array of items that do not match the filter
+ */
 function removeFiltered<Item>(
 	array: Item[],
 	filter: (item: Item, index: number, array: Item[]) => boolean,
 ): unknown[];
 
+/**
+ * Get a filtered array of items that do not match the given item
+ * @param array Array to search in
+ * @param item Item to match against
+ * @returns Filtered array of items that do not match the given item
+ */
 function removeFiltered<Item>(array: Item[], item: Item): unknown[];
 
 function removeFiltered(array: unknown[], ...parameters: unknown[]): unknown[] {

package/src/array/find.ts

@@ -1,10 +1,10 @@
-import {FIND_VALUE_VALUE, findValue} from '../internal/array/find';
+import {FIND_VALUE_ITEM, findValue} from '../internal/array/find';
 import type {PlainObject} from '../models';
 
 // #region Functions
 
 /**
- * Get the first items matching the given value
+ * Get the first item matching the given value
  * @param array Array to search in
  * @param callback Callback to get an item's value for matching
  * @param value Value to match against
@@ -48,8 +48,8 @@ export function find<Item>(
  */
 export function find<Item>(array: Item[], value: Item): Item | undefined;
 
-export function find<Item>(array: unknown[], ...parameters: unknown[]): Item | undefined {
-	return findValue(FIND_VALUE_VALUE, array, parameters) as Item | undefined;
+export function find(array: unknown[], ...parameters: unknown[]): unknown {
+	return findValue(FIND_VALUE_ITEM, array, parameters, false);
 }
 
 // #endregion

package/src/array/first.ts

@@ -0,0 +1,113 @@
+import {findAbsoluteValueOrDefault} from '../internal/array/find';
+import type {PlainObject} from '../models';
+
+// #region Functions
+
+/**
+ * Get the first item matching the given value
+ * @param array Array to search in
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns First item that matches the value, or `undefined` if no match is found
+ */
+export function first<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
+	array: Item[],
+	callback: Callback,
+	value: ReturnType<Callback>,
+): Item | undefined;
+
+/**
+ * Get the first item matching the given value by key
+ * @param array Array to search in
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns First item that matches the value, or `undefined` if no match is found
+ */
+export function first<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	key: ItemKey,
+	value: Item[ItemKey],
+): Item | undefined;
+
+/**
+ * Get the first item matching the filter
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @returns First item that matches the filter, or `undefined` if no match is found
+ */
+export function first<Item>(
+	array: Item[],
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): Item | undefined;
+
+/**
+ * Get the first item from an array
+ * @param array Array to get from
+ * @return First item from the array, or `undefined` if the array is empty
+ */
+export function first<Item>(array: Item[]): Item | undefined;
+
+export function first(array: unknown[], ...parameters: unknown[]): unknown {
+	return findAbsoluteValueOrDefault(array, parameters, undefined, false, false);
+}
+
+first.default = firstOrDefault;
+
+/**
+ * Get the first item matching the given value
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns First item that matches the value, or the default value if no match is found
+ */
+function firstOrDefault<
+	Item,
+	Callback extends (item: Item, index: number, array: Item[]) => unknown,
+>(array: Item[], defaultValue: Item, callback: Callback, value: ReturnType<Callback>): Item;
+
+/**
+ * Get the first item matching the given value by key
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns First item that matches the value, or the default value if no match is found
+ */
+function firstOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	defaultValue: Item,
+	key: ItemKey,
+	value: Item[ItemKey],
+): Item;
+
+/**
+ * Get the first item matching the filter
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param filter Filter callback to match items
+ * @returns First item that matches the filter, or the default value if no match is found
+ */
+function firstOrDefault<Item>(
+	array: Item[],
+	defaultValue: Item,
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): Item;
+
+/**
+ * Get the first item from an array
+ * @param array Array to get from
+ * @param defaultValue Default value to return if the array is empty
+ * @return First item from the array, or the default value if the array is empty
+ */
+function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
+
+function firstOrDefault(
+	array: unknown[],
+	defaultValue: unknown,
+	...parameters: unknown[]
+): unknown {
+	return findAbsoluteValueOrDefault(array, parameters, defaultValue, true, false);
+}
+
+// #endregion

package/src/array/index.ts

@@ -15,6 +15,7 @@ export * from './partition';
 export * from './position';
 export * from './push';
 export * from './select';
+export * from './single';
 export * from './slice';
 export * from './splice';
 export * from './to-set';

package/src/array/last.ts

@@ -0,0 +1,109 @@
+import {findAbsoluteValueOrDefault} from '../internal/array/find';
+import type {PlainObject} from '../models';
+
+// #region Functions
+
+/**
+ * Get the last items matching the given value
+ * @param array Array to search in
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns Last item that matches the value, or `undefined` if no match is found
+ */
+export function last<Item, Callback extends (item: Item, index: number, array: Item[]) => unknown>(
+	array: Item[],
+	callback: Callback,
+	value: ReturnType<Callback>,
+): Item | undefined;
+
+/**
+ * Get the first item matching the given value by key
+ * @param array Array to search in
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns Last item that matches the value, or `undefined` if no match is found
+ */
+export function last<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	key: ItemKey,
+	value: Item[ItemKey],
+): Item | undefined;
+
+/**
+ * Get the last item matching the filter
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @returns Last item that matches the filter, or `undefined` if no match is found
+ */
+export function last<Item>(
+	array: Item[],
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): Item | undefined;
+
+/**
+ * Get the last item from an array
+ * @param array Array to get from
+ * @return Last item from the array, or `undefined` if the array is empty
+ */
+export function last<Item>(array: Item[]): Item | undefined;
+
+export function last(array: unknown[], ...parameters: unknown[]): unknown {
+	return findAbsoluteValueOrDefault(array, parameters, undefined, false, true);
+}
+
+last.default = lastOrDefault;
+
+/**
+ * Get the last item matching the given value
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns Last item that matches the value, or the default value if no match is found
+ */
+function lastOrDefault<
+	Item,
+	Callback extends (item: Item, index: number, array: Item[]) => unknown,
+>(array: Item[], defaultValue: Item, callback: Callback, value: ReturnType<Callback>): Item;
+
+/**
+ * Get the last item matching the given value by key
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns Last item that matches the value, or the default value if no match is found
+ */
+function lastOrDefault<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	defaultValue: Item,
+	key: ItemKey,
+	value: Item[ItemKey],
+): Item;
+
+/**
+ * Get the last item matching the filter
+ * @param array Array to search in
+ * @param defaultValue Default value to return if no match is found
+ * @param filter Filter callback to match items
+ * @returns Last item that matches the filter, or the default value if no match is found
+ */
+function lastOrDefault<Item>(
+	array: Item[],
+	defaultValue: Item,
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): Item;
+
+/**
+ * Get the last item from an array
+ * @param array Array to get from
+ * @param defaultValue Default value to return if the array is empty
+ * @return Last item from the array, or the default value if the array is empty
+ */
+function lastOrDefault<Item>(array: Item[], defaultValue: Item): Item;
+
+function lastOrDefault(array: unknown[], defaultValue: unknown, ...parameters: unknown[]): unknown {
+	return findAbsoluteValueOrDefault(array, parameters, defaultValue, true, true);
+}
+
+// #endregion

package/src/array/select.ts

@@ -20,6 +20,25 @@ export function select<
 	mapCallback: MapCallback,
 ): Array<ReturnType<MapCallback>>;
 
+/**
+ * Get a filtered and mapped array of items
+ * @param array Array to search in
+ * @param filterCallback Callback to get an item's value for matching
+ * @param filterValue Value to match against
+ * @param mapKey Key to get an item's value for mapping
+ * @returns Filtered and mapped array of items
+ */
+export function select<
+	Item extends PlainObject,
+	FilterCallback extends (item: Item, index: number, array: Item[]) => unknown,
+	MapKey extends keyof Item,
+>(
+	array: Item[],
+	filterCallback: FilterCallback,
+	filterValue: ReturnType<FilterCallback>,
+	mapKey: MapKey,
+): Array<Item[MapKey]>;
+
 /**
  * Get a filtered and mapped array of items
  * @param array Array to search in
@@ -39,6 +58,25 @@ export function select<
 	mapCallback: MapCallback,
 ): Array<ReturnType<MapCallback>>;
 
+/**
+ * Get a filtered and mapped array of items
+ * @param array Array to search in
+ * @param filterKey Key to get an item's value for matching
+ * @param filterValue Value to match against
+ * @param mapKey Key to get an item's value for mapping
+ * @returns Filtered and mapped array of items
+ */
+export function select<
+	Item extends PlainObject,
+	ItemKey extends keyof Item,
+	MapKey extends keyof Item,
+>(
+	array: Item[],
+	filterKey: ItemKey,
+	filterValue: Item[ItemKey],
+	mapKey: MapKey,
+): Array<Item[MapKey]>;
+
 /**
  * Get a filtered and mapped array of items
  * @param array Array to search in
@@ -57,6 +95,24 @@ export function select<
 	mapCallback: MapCallback,
 ): Array<ReturnType<MapCallback>>;
 
+/**
+ * Get a filtered and mapped array of items
+ * @param array Array to search in
+ * @param filterCallback Filter callback to match items
+ * @param mapKey Key to get an item's value for mapping
+ * @returns Filtered and mapped array of items
+ */
+export function select<
+	Item extends PlainObject,
+	FilterCallback extends (item: Item, index: number, array: Item[]) => unknown,
+	MapKey extends keyof Item,
+>(
+	array: Item[],
+	filterCallback: FilterCallback,
+	filterValue: ReturnType<FilterCallback>,
+	mapKey: MapKey,
+): Array<Item[MapKey]>;
+
 /**
  * Get a filtered and mapped array of items
  * @param array Array to search in
@@ -73,6 +129,19 @@ export function select<
 	map: MapCallback,
 ): Array<ReturnType<MapCallback>>;
 
+/**
+ * Get a filtered and mapped array of items
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @param map Key to get an item's value for mapping
+ * @returns Filtered and mapped array of items
+ */
+export function select<Item extends PlainObject, MapKey extends keyof Item>(
+	array: Item[],
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+	map: MapKey,
+): Array<Item[MapKey]>;
+
 /**
  * Get a filtered and mapped array of items
  * @param array Array to search in
@@ -85,8 +154,23 @@ export function select<
 	MapCallback extends (item: Item, index: number, array: Item[]) => unknown,
 >(array: Item[], filter: Item, map: MapCallback): Array<ReturnType<MapCallback>>;
 
+/**
+ * Get a filtered and mapped array of items
+ * @param array Array to search in
+ * @param item Item to match against
+ * @param map Key to get an item's value for mapping
+ * @returns Filtered and mapped array of items
+ */
+export function select<Item extends PlainObject, MapKey extends keyof Item>(
+	array: Item[],
+	filter: Item,
+	map: MapKey,
+): Array<Item[MapKey]>;
+
 export function select(array: unknown[], ...parameters: unknown[]): unknown[] {
 	const mapper = parameters.pop();
 
 	return findValues(FIND_VALUES_ALL, array, parameters, mapper).matched;
 }
+
+// #endregion

package/src/array/single.ts

@@ -0,0 +1,64 @@
+import {FIND_VALUES_ALL, findValues} from '../internal/array/find';
+import type {PlainObject} from '../models';
+
+// #region Functions
+
+/**
+ * Get the _only_ item matching the given value
+ *
+ * Throws an error if multiple items match the value
+ * @param array Array to search in
+ * @param callback Callback to get an item's value for matching
+ * @param value Value to match against
+ * @returns Only item that matches the value, or `undefined` if no match is found
+ */
+export function single<
+	Item,
+	Callback extends (item: Item, index: number, array: Item[]) => unknown,
+>(array: Item[], callback: Callback, value: ReturnType<Callback>): Item | undefined;
+
+/**
+ * Get the _only_ item matching the given value by key
+ *
+ * Throws an error if multiple items match the value
+ * @param array Array to search in
+ * @param key Key to get an item's value for matching
+ * @param value Value to match against
+ * @returns Only item that matches the value, or `undefined` if no match is found
+ */
+export function single<Item extends PlainObject, ItemKey extends keyof Item>(
+	array: Item[],
+	key: ItemKey,
+	value: Item[ItemKey],
+): Item | undefined;
+
+/**
+ * Get the _only_ item matching the filter
+ *
+ * Throws an error if multiple items match the filter
+ * @param array Array to search in
+ * @param filter Filter callback to match items
+ * @returns Only item that matches the filter, or `undefined` if no match is found
+ */
+export function single<Item>(
+	array: Item[],
+	filter: (item: Item, index: number, array: Item[]) => boolean,
+): Item | undefined;
+
+export function single(array: unknown[], ...parameters: unknown[]): unknown {
+	const {matched} = findValues(FIND_VALUES_ALL, array, parameters);
+
+	if (matched.length > 1) {
+		throw new Error(MESSAGE);
+	}
+
+	return matched[0];
+}
+
+// #endregion
+
+// #region Variables
+
+const MESSAGE = 'Multiple items were found';
+
+// #endregion

package/src/index.ts

@@ -1,6 +1,8 @@
 export * from './array/filter';
+export * from './array/first';
 export * from './array/group-by';
 export * from './array/index';
+export * from './array/last';
 export * from './array/move';
 export * from './array/sort';
 export * from './array/swap';

package/src/internal/array/find.ts

@@ -1,8 +1,8 @@
-import {getArrayCallbacks} from './callbacks';
+import {getArrayCallback, getArrayCallbacks} from './callbacks';
 
 // #region Types
 
-type FindValueType = 'index' | 'value';
+type FindValueType = 'index' | 'item';
 
 type FindValuesResult = {
 	matched: unknown[];
@@ -21,14 +21,19 @@ type Parameters = {
 
 // #region Functions
 
-export function findValue(type: FindValueType, array: unknown[], parameters: unknown[]): unknown {
+export function findValue(
+	type: FindValueType,
+	array: unknown[],
+	parameters: unknown[],
+	reversed: boolean,
+): unknown {
 	const findIndex = type === FIND_VALUE_INDEX;
 
 	if (!Array.isArray(array) || array.length === 0) {
 		return findIndex ? -1 : undefined;
 	}
 
-	const {bool, key, value} = getParameters(parameters);
+	const {bool, key, value} = getFindParameters(parameters);
 
 	const callbacks = getArrayCallbacks(bool, key);
 
@@ -42,7 +47,7 @@ export function findValue(type: FindValueType, array: unknown[], parameters: unk
 		return findIndex ? index : array[index];
 	}
 
-	return findValueInArray(array, callbacks.keyed, value, findIndex);
+	return findValueInArray(array, callbacks.keyed, value, findIndex, reversed);
 }
 
 function findValueInArray(
@@ -50,11 +55,12 @@ function findValueInArray(
 	callback: ((item: unknown, index: number, array: unknown[]) => boolean) | undefined,
 	value: unknown,
 	findIndex: boolean,
+	reversed: boolean,
 ): unknown {
 	const {length} = array;
 
 	for (let index = 0; index < length; index += 1) {
-		const item = array[index];
+		const item = reversed ? array.at(-(index + 1)) : array[index];
 
 		if (Object.is(callback?.(item, index, array), value)) {
 			return findIndex ? index : item;
@@ -64,6 +70,26 @@ function findValueInArray(
 	return findIndex ? -1 : undefined;
 }
 
+export function findAbsoluteValueOrDefault(
+	array: unknown[],
+	parameters: unknown[],
+	defaultValue: unknown,
+	useDefaultValue: boolean,
+	reversed: boolean,
+): unknown {
+	if (parameters.length === 0) {
+		if (Array.isArray(array) && array.length > 0) {
+			return reversed ? array.at(-1) : array[0];
+		}
+
+		return useDefaultValue ? defaultValue : undefined;
+	}
+
+	const index = findValue(FIND_VALUE_INDEX, array, parameters, reversed) as number;
+
+	return index > -1 ? array[index] : useDefaultValue ? defaultValue : undefined;
+}
+
 export function findValues(
 	type: FindValuesType,
 	array: unknown[],
@@ -80,7 +106,7 @@ export function findValues(
 	}
 
 	const {length} = array;
-	const {bool, key, value} = getParameters(parameters);
+	const {bool, key, value} = getFindParameters(parameters);
 	const callbacks = getArrayCallbacks(bool, key);
 
 	if (type === FIND_VALUES_UNIQUE && callbacks?.keyed == null && length >= UNIQUE_THRESHOLD) {
@@ -89,7 +115,7 @@ export function findValues(
 		return result;
 	}
 
-	const mapCallback = typeof mapper === 'function' ? mapper : undefined;
+	const mapCallback = getArrayCallback(mapper);
 
 	if (callbacks?.bool != null || (type === FIND_VALUES_ALL && key == null)) {
 		const callback = callbacks?.bool ?? (item => Object.is(item, value));
@@ -127,7 +153,7 @@ export function findValues(
 	return result;
 }
 
-function getParameters(original: unknown[]): Parameters {
+export function getFindParameters(original: unknown[]): Parameters {
 	const {length} = original;
 
 	return {
@@ -143,7 +169,7 @@ function getParameters(original: unknown[]): Parameters {
 
 export const FIND_VALUE_INDEX: FindValueType = 'index';
 
-export const FIND_VALUE_VALUE: FindValueType = 'value';
+export const FIND_VALUE_ITEM: FindValueType = 'item';
 
 export const FIND_VALUES_ALL: FindValuesType = 'all';