@oscarpalmer/atoms 0.175.0 → 0.177.0

package/dist/array/exists.mjs

@@ -2,7 +2,7 @@ import { FIND_VALUE_INDEX, findValue } from "../internal/array/find.mjs";
 //#region src/array/exists.ts
 function exists(array, ...parameters) {
 	if (parameters.length === 1 && typeof parameters[0] !== "function") return Array.isArray(array) ? array.includes(parameters[0]) : false;
-	return findValue(FIND_VALUE_INDEX, array, parameters) > -1;
+	return findValue(FIND_VALUE_INDEX, array, parameters, false) > -1;
 }
 //#endregion
 export { exists };

package/dist/array/filter.d.mts

@@ -34,9 +34,35 @@ declare function filter<Item>(array: Item[], item: Item): Item[];
 declare namespace filter {
   var remove: typeof 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
+ */
 declare 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
+ */
 declare 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
+ */
 declare 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
+ */
 declare function removeFiltered<Item>(array: Item[], item: Item): unknown[];
 //#endregion
 export { filter };

package/dist/array/find.d.mts

@@ -2,7 +2,7 @@ import { PlainObject } from "../models.mjs";
 
 //#region src/array/find.d.ts
 /**
- * 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

package/dist/array/find.mjs

@@ -1,7 +1,7 @@
-import { FIND_VALUE_VALUE, findValue } from "../internal/array/find.mjs";
+import { FIND_VALUE_ITEM, findValue } from "../internal/array/find.mjs";
 //#region src/array/find.ts
 function find(array, ...parameters) {
-	return findValue(FIND_VALUE_VALUE, array, parameters);
+	return findValue(FIND_VALUE_ITEM, array, parameters, false);
 }
 //#endregion
 export { find };

package/dist/array/first.d.mts

@@ -0,0 +1,71 @@
+import { PlainObject } from "../models.mjs";
+
+//#region src/array/first.d.ts
+/**
+ * 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare function first<Item>(array: Item[]): Item | undefined;
+declare namespace first {
+  var _a: typeof firstOrDefault;
+  export { _a as default };
+}
+/**
+ * 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare function firstOrDefault<Item>(array: Item[], defaultValue: Item): Item;
+//#endregion
+export { first };

package/dist/array/first.mjs

@@ -0,0 +1,11 @@
+import { findAbsoluteValueOrDefault } from "../internal/array/find.mjs";
+//#region src/array/first.ts
+function first(array, ...parameters) {
+	return findAbsoluteValueOrDefault(array, parameters, void 0, false, false);
+}
+first.default = firstOrDefault;
+function firstOrDefault(array, defaultValue, ...parameters) {
+	return findAbsoluteValueOrDefault(array, parameters, defaultValue, true, false);
+}
+//#endregion
+export { first };

package/dist/array/index.d.mts

@@ -14,6 +14,7 @@ import { partition } from "./partition.mjs";
 import { ArrayPosition, endsWithArray, getArrayPosition, includesArray, indexOfArray, startsWithArray } from "./position.mjs";
 import { push } from "./push.mjs";
 import { select } from "./select.mjs";
+import { single } from "./single.mjs";
 import { drop, slice, take } from "./slice.mjs";
 import { splice } from "./splice.mjs";
 import { toSet } from "./to-set.mjs";
@@ -21,4 +22,4 @@ import { toggle } from "./toggle.mjs";
 import { union } from "./union.mjs";
 import { unique } from "./unique.mjs";
 import { update } from "./update.mjs";
-export { ArrayPosition, chunk, compact, difference, drop, endsWithArray, exists, find, flatten, getArray, getArrayPosition, includesArray, indexOf, indexOfArray, insert, intersection, partition, push, range, select, shuffle, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };
+export { ArrayPosition, chunk, compact, difference, drop, endsWithArray, exists, find, flatten, getArray, getArrayPosition, includesArray, indexOf, indexOfArray, insert, intersection, partition, push, range, select, shuffle, single, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };

package/dist/array/index.mjs

@@ -14,6 +14,7 @@ import { partition } from "./partition.mjs";
 import { endsWithArray, getArrayPosition, includesArray, indexOfArray, startsWithArray } from "./position.mjs";
 import { push } from "./push.mjs";
 import { select } from "./select.mjs";
+import { single } from "./single.mjs";
 import { drop, slice, take } from "./slice.mjs";
 import { splice } from "./splice.mjs";
 import { toSet } from "./to-set.mjs";
@@ -21,4 +22,4 @@ import { toggle } from "./toggle.mjs";
 import { union } from "./union.mjs";
 import { unique } from "./unique.mjs";
 import { update } from "./update.mjs";
-export { chunk, compact, difference, drop, endsWithArray, exists, find, flatten, getArray, getArrayPosition, includesArray, indexOf, indexOfArray, insert, intersection, partition, push, range, select, shuffle, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };
+export { chunk, compact, difference, drop, endsWithArray, exists, find, flatten, getArray, getArrayPosition, includesArray, indexOf, indexOfArray, insert, intersection, partition, push, range, select, shuffle, single, slice, splice, startsWithArray, take, times, toSet, toggle, union, unique, update };

package/dist/array/last.d.mts

@@ -0,0 +1,71 @@
+import { PlainObject } from "../models.mjs";
+
+//#region src/array/last.d.ts
+/**
+ * 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare function last<Item>(array: Item[]): Item | undefined;
+declare namespace last {
+  var _a: typeof lastOrDefault;
+  export { _a as default };
+}
+/**
+ * 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare function lastOrDefault<Item>(array: Item[], defaultValue: Item): Item;
+//#endregion
+export { last };

package/dist/array/last.mjs

@@ -0,0 +1,11 @@
+import { findAbsoluteValueOrDefault } from "../internal/array/find.mjs";
+//#region src/array/last.ts
+function last(array, ...parameters) {
+	return findAbsoluteValueOrDefault(array, parameters, void 0, false, true);
+}
+last.default = lastOrDefault;
+function lastOrDefault(array, defaultValue, ...parameters) {
+	return findAbsoluteValueOrDefault(array, parameters, defaultValue, true, true);
+}
+//#endregion
+export { last };

package/dist/array/select.d.mts

@@ -10,6 +10,15 @@ import { PlainObject } from "../models.mjs";
  * @returns Filtered and mapped array of items
  */
 declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, 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
+ */
+declare 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
@@ -19,6 +28,15 @@ declare function select<Item, FilterCallback extends (item: Item, index: number,
  * @returns Filtered and mapped array of items
  */
 declare function select<Item extends PlainObject, ItemKey extends keyof Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], 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
+ */
+declare 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
@@ -27,6 +45,14 @@ declare function select<Item extends PlainObject, ItemKey extends keyof Item, Ma
  * @returns Filtered and mapped array of items
  */
 declare function select<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, 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
+ */
+declare 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
@@ -35,6 +61,14 @@ declare function select<Item, FilterCallback extends (item: Item, index: number,
  * @returns Filtered and mapped array of items
  */
 declare function select<Item, MapCallback extends (item: Item, index: number, array: Item[]) => unknown>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, 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
+ */
+declare 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
@@ -43,5 +77,13 @@ declare function select<Item, MapCallback extends (item: Item, index: number, ar
  * @returns Filtered and mapped array of items
  */
 declare function select<Item, 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
+ */
+declare function select<Item extends PlainObject, MapKey extends keyof Item>(array: Item[], filter: Item, map: MapKey): Array<Item[MapKey]>;
 //#endregion
 export { select };

package/dist/array/single.d.mts

@@ -0,0 +1,34 @@
+import { PlainObject } from "../models.mjs";
+
+//#region src/array/single.d.ts
+/**
+ * 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
+ */
+declare 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
+ */
+declare 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
+ */
+declare function single<Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean): Item | undefined;
+//#endregion
+export { single };

package/dist/array/single.mjs

@@ -0,0 +1,10 @@
+import { findValues } from "../internal/array/find.mjs";
+//#region src/array/single.ts
+function single(array, ...parameters) {
+	const { matched } = findValues("all", array, parameters);
+	if (matched.length > 1) throw new Error(MESSAGE);
+	return matched[0];
+}
+const MESSAGE = "Multiple items were found";
+//#endregion
+export { single };