@oscarpalmer/atoms 0.176.0 → 0.178.0

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/reverse.ts

@@ -0,0 +1,23 @@
+export function reverse<Item>(array: Item[]): Item[] {
+	if (!Array.isArray(array)) {
+		return [];
+	}
+
+	const {length} = array;
+
+	if (length < 2) {
+		return array;
+	}
+
+	const half = Math.floor(length / 2);
+
+	for (let firstIndex = 0; firstIndex < half; firstIndex += 1) {
+		const temporaryItem = array[firstIndex];
+		const secondIndex = length - 1 - firstIndex;
+
+		array[firstIndex] = array[secondIndex];
+		array[secondIndex] = temporaryItem;
+	}
+
+	return array;
+}

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';
 

package/src/internal/is.ts

@@ -49,6 +49,95 @@ export function isKey(value: unknown): value is Key {
 	return typeof value === 'number' || typeof value === 'string';
 }
 
+/**
+ * Is the value not an array or a plain object?
+ * @param value Value to check
+ * @returns `true` if the value is not an array or a plain object, otherwise `false`
+ */
+export function isNonArrayOrPlainObject<Value>(
+	value: Value,
+): value is Exclude<Value, ArrayOrPlainObject> {
+	return !isArrayOrPlainObject(value);
+}
+
+/**
+ * Is the value not a constructor function?
+ * @param value Value to check
+ * @returns `true` if the value is not a constructor function, otherwise `false`
+ */
+export function isNonConstructor<Value>(value: Value): value is Exclude<Value, Constructor> {
+	return !isConstructor(value);
+}
+
+/**
+ * Is the value not an instance of the constructor?
+ * @param constructor Class constructor
+ * @param value Value to check
+ * @returns `true` if the value is not an instance of the constructor, otherwise `false`
+ */
+export function isNonInstanceOf<Instance, Value>(
+	constructor: Constructor<Instance>,
+	value: Value,
+): value is Exclude<Value, Instance> {
+	return !isInstanceOf(constructor, value);
+}
+
+/**
+ * Is the value not a key?
+ * @param value Value to check
+ * @returns `true` if the value is not a `Key` _(`number` or `string`)_, otherwise `false`
+ */
+export function isNonKey<Value>(value: Value): value is Exclude<Value, Key> {
+	return !isKey(value);
+}
+
+/**
+ * Is the value not a number?
+ * @param value Value to check
+ * @returns `true` if the value is not a `number`, otherwise `false`
+ */
+export function isNonNumber<Value>(value: Value): value is Exclude<Value, number> {
+	return !isNumber(value);
+}
+
+/**
+ * Is the value not a plain object?
+ * @param value Value to check
+ * @returns `true` if the value is not a plain object, otherwise `false`
+ */
+export function isNonPlainObject<Value>(value: Value): value is Exclude<Value, PlainObject> {
+	return !isPlainObject(value);
+}
+
+/**
+ * Is the value not a primitive value?
+ * @param value Value to check
+ * @returns `true` if the value is not a primitive value, otherwise `false`
+ */
+export function isNonPrimitive<Value>(value: Value): value is Exclude<Value, Primitive> {
+	return !isPrimitive(value);
+}
+
+/**
+ * Is the value not a template strings array?
+ * @param value Value to check
+ * @returns `true` if the value is not a `TemplateStringsArray`, otherwise `false`
+ */
+export function isNonTemplateStringsArray<Value>(
+	value: Value,
+): value is Exclude<Value, TemplateStringsArray> {
+	return !isTemplateStringsArray(value);
+}
+
+/**
+ * Is the value not a typed array?
+ * @param value Value to check
+ * @returns `true` if the value is not a typed array, otherwise `false`
+ */
+export function isNonTypedArray<Value>(value: Value): value is Exclude<Value, TypedArray> {
+	return !isTypedArray(value);
+}
+
 /**
  * Is the value a number?
  * @param value Value to check
@@ -87,7 +176,28 @@ export function isPlainObject(value: unknown): value is PlainObject {
  * @returns `true` if the value matches, otherwise `false`
  */
 export function isPrimitive(value: unknown): value is Primitive {
-	return value == null || EXPRESSION_PRIMITIVE.test(typeof value);
+	if (value == null) {
+		return true;
+	}
+
+	const type = typeof value;
+
+	return (
+		type === 'bigint' ||
+		type === 'boolean' ||
+		type === 'number' ||
+		type === 'string' ||
+		type === 'symbol'
+	);
+}
+
+/**
+ * Is the value a template strings array?
+ * @param value Value to check
+ * @returns `true` if the value is a `TemplateStringsArray`, otherwise `false`
+ */
+export function isTemplateStringsArray(value: unknown): value is TemplateStringsArray {
+	return Array.isArray(value) && Array.isArray((value as unknown as TemplateStringsArray).raw);
 }
 
 /**
@@ -96,7 +206,7 @@ export function isPrimitive(value: unknown): value is Primitive {
  * @returns `true` if the value is a typed array, otherwise `false`
  */
 export function isTypedArray(value: unknown): value is TypedArray {
-	TYPED_ARRAYS ??= new Set<unknown>([
+	(isTypedArray as any).types ??= new Set<unknown>([
 		Int8Array,
 		Uint8Array,
 		Uint8ClampedArray,
@@ -110,15 +220,7 @@ export function isTypedArray(value: unknown): value is TypedArray {
 		BigUint64Array,
 	]);
 
-	return TYPED_ARRAYS.has((value as TypedArray)?.constructor);
+	return (isTypedArray as any).types.has((value as TypedArray)?.constructor);
 }
 
 // #endregion
-
-// #region Variables
-
-const EXPRESSION_PRIMITIVE = /^(bigint|boolean|number|string|symbol)$/;
-
-let TYPED_ARRAYS: Set<unknown>;
-
-// #endregion