@oscarpalmer/atoms 0.176.0 → 0.178.0

package/dist/internal/is.mjs

@@ -33,6 +33,79 @@ function isKey(value) {
 	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`
+*/
+function isNonArrayOrPlainObject(value) {
+	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`
+*/
+function isNonConstructor(value) {
+	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`
+*/
+function isNonInstanceOf(constructor, value) {
+	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`
+*/
+function isNonKey(value) {
+	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`
+*/
+function isNonNumber(value) {
+	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`
+*/
+function isNonPlainObject(value) {
+	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`
+*/
+function isNonPrimitive(value) {
+	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`
+*/
+function isNonTemplateStringsArray(value) {
+	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`
+*/
+function isNonTypedArray(value) {
+	return !isTypedArray(value);
+}
+/**
 * Is the value a number?
 * @param value Value to check
 * @returns `true` if the value is a `number`, otherwise `false`
@@ -57,7 +130,17 @@ function isPlainObject(value) {
 * @returns `true` if the value matches, otherwise `false`
 */
 function isPrimitive(value) {
-	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`
+*/
+function isTemplateStringsArray(value) {
+	return Array.isArray(value) && Array.isArray(value.raw);
 }
 /**
 * Is the value a typed array?
@@ -65,7 +148,7 @@ function isPrimitive(value) {
 * @returns `true` if the value is a typed array, otherwise `false`
 */
 function isTypedArray(value) {
-	TYPED_ARRAYS ??= new Set([
+	isTypedArray.types ??= new Set([
 		Int8Array,
 		Uint8Array,
 		Uint8ClampedArray,
@@ -78,9 +161,7 @@ function isTypedArray(value) {
 		BigInt64Array,
 		BigUint64Array
 	]);
-	return TYPED_ARRAYS.has(value?.constructor);
+	return isTypedArray.types.has(value?.constructor);
 }
-const EXPRESSION_PRIMITIVE = /^(bigint|boolean|number|string|symbol)$/;
-let TYPED_ARRAYS;
 //#endregion
-export { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNumber, isPlainObject, isPrimitive, isTypedArray };
+export { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonInstanceOf, isNonKey, isNonNumber, isNonPlainObject, isNonPrimitive, isNonTemplateStringsArray, isNonTypedArray, isNumber, isPlainObject, isPrimitive, isTemplateStringsArray, isTypedArray };

package/dist/is.d.mts

@@ -1,4 +1,4 @@
-import { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNumber, isPlainObject, isPrimitive, isTypedArray } from "./internal/is.mjs";
+import { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonInstanceOf, isNonKey, isNonNumber, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNumber, isPlainObject, isPrimitive, isTypedArray } from "./internal/is.mjs";
 
 //#region src/is.d.ts
 /**
@@ -7,12 +7,42 @@ import { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNumber, isP
  * @returns `true` if the value is considered empty, otherwise `false`
  */
 declare function isEmpty(value: unknown): boolean;
+/**
+ * Is the value not empty, or holding non-empty values?
+ * @param value Value to check
+ * @returns `true` if the value is not considered empty, otherwise `false`
+ */
+declare function isNonEmpty(value: unknown): boolean;
 /**
  * Is the value not `undefined` or `null`?
  * @param value Value to check
  * @returns `true` if the value is not `undefined` or `null`, otherwise `false`
  */
-declare function isNonNullable(value: unknown): value is Exclude<unknown, undefined | null>;
+declare function isNonNullable<Value>(value: Value): value is Exclude<Value, undefined | null>;
+/**
+ * Is the value not `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
+ * @param value Value to check
+ * @returns `true` if the value is not `undefined`, `null`, or matches an empty string, otherwise `false`
+ */
+declare function isNonNullableOrEmpty<Value>(value: Value): value is Exclude<Value, undefined | null | ''>;
+/**
+ * Is the value not `undefined`, `null`, or stringified as a whitespace-only string?
+ * @param value Value to check
+ * @returns `true` if the value is not `undefined`, `null`, or matches a whitespace-only string, otherwise `false`
+ */
+declare function isNonNullableOrWhitespace<Value>(value: Value): value is Exclude<Value, undefined | null | ''>;
+/**
+ * Is the value not a number or a number-like string?
+ * @param value Value to check
+ * @returns `true` if the value is not a number or a number-like string, otherwise `false`
+ */
+declare function isNonNumerical<Value>(value: Value): value is Exclude<Value, number | `${number}`>;
+/**
+ * Is the value not an object _(or function)_?
+ * @param value Value to check
+ * @returns `true` if the value is not an object, otherwise `false`
+ */
+declare function isNonObject<Value>(value: Value): value is Exclude<Value, object>;
 /**
  * Is the value `undefined` or `null`?
  * @param value Value to check
@@ -20,21 +50,21 @@ declare function isNonNullable(value: unknown): value is Exclude<unknown, undefi
  */
 declare function isNullable(value: unknown): value is undefined | null;
 /**
- * Is the value `undefined`, `null`, or an empty _(no whitespace)_ string?
+ * Is the value `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
  * @param value Value to check
- * @returns `true` if the value is nullable or an empty string, otherwise `false`
+ * @returns `true` if the value is nullable or matches an empty string, otherwise `false`
  */
 declare function isNullableOrEmpty(value: unknown): value is undefined | null | '';
 /**
- * Is the value `undefined`, `null`, or a whitespace-only string?
+ * Is the value `undefined`, `null`, or stringified as a whitespace-only string?
  * @param value Value to check
- * @returns `true` if the value is nullable or a whitespace-only string, otherwise `false`
+ * @returns `true` if the value is nullable or matches a whitespace-only string, otherwise `false`
  */
 declare function isNullableOrWhitespace(value: unknown): value is undefined | null | '';
 /**
  * Is the value a number or a number-like string?
  * @param value Value to check
- * @returns `true` if the value is a number or a parseable string, otherwise `false`
+ * @returns `true` if the value is a number or a number-like string, otherwise `false`
  */
 declare function isNumerical(value: unknown): value is number | `${number}`;
 /**
@@ -44,4 +74,4 @@ declare function isNumerical(value: unknown): value is number | `${number}`;
  */
 declare function isObject(value: unknown): value is object;
 //#endregion
-export { isArrayOrPlainObject, isConstructor, isEmpty, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive, isTypedArray };
+export { isArrayOrPlainObject, isConstructor, isEmpty, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive, isTypedArray };

package/dist/is.mjs

@@ -1,4 +1,4 @@
-import { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNumber, isPlainObject, isPrimitive, isTypedArray } from "./internal/is.mjs";
+import { isArrayOrPlainObject, isConstructor, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonInstanceOf, isNonKey, isNonNumber, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNumber, isPlainObject, isPrimitive, isTypedArray } from "./internal/is.mjs";
 import { getArray } from "./array/get.mjs";
 import { getString } from "./internal/string.mjs";
 //#region src/is.ts
@@ -16,6 +16,14 @@ function isEmpty(value) {
 	return true;
 }
 /**
+* Is the value not empty, or holding non-empty values?
+* @param value Value to check
+* @returns `true` if the value is not considered empty, otherwise `false`
+*/
+function isNonEmpty(value) {
+	return !isEmpty(value);
+}
+/**
 * Is the value not `undefined` or `null`?
 * @param value Value to check
 * @returns `true` if the value is not `undefined` or `null`, otherwise `false`
@@ -24,6 +32,38 @@ function isNonNullable(value) {
 	return value != null;
 }
 /**
+* Is the value not `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
+* @param value Value to check
+* @returns `true` if the value is not `undefined`, `null`, or matches an empty string, otherwise `false`
+*/
+function isNonNullableOrEmpty(value) {
+	return value != null && getString(value) !== "";
+}
+/**
+* Is the value not `undefined`, `null`, or stringified as a whitespace-only string?
+* @param value Value to check
+* @returns `true` if the value is not `undefined`, `null`, or matches a whitespace-only string, otherwise `false`
+*/
+function isNonNullableOrWhitespace(value) {
+	return value != null && !EXPRESSION_WHITESPACE.test(getString(value));
+}
+/**
+* Is the value not a number or a number-like string?
+* @param value Value to check
+* @returns `true` if the value is not a number or a number-like string, otherwise `false`
+*/
+function isNonNumerical(value) {
+	return !isNumerical(value);
+}
+/**
+* Is the value not an object _(or function)_?
+* @param value Value to check
+* @returns `true` if the value is not an object, otherwise `false`
+*/
+function isNonObject(value) {
+	return !isObject(value);
+}
+/**
 * Is the value `undefined` or `null`?
 * @param value Value to check
 * @returns `true` if the value is `undefined` or `null`, otherwise `false`
@@ -32,17 +72,17 @@ function isNullable(value) {
 	return value == null;
 }
 /**
-* Is the value `undefined`, `null`, or an empty _(no whitespace)_ string?
+* Is the value `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
 * @param value Value to check
-* @returns `true` if the value is nullable or an empty string, otherwise `false`
+* @returns `true` if the value is nullable or matches an empty string, otherwise `false`
 */
 function isNullableOrEmpty(value) {
 	return value == null || getString(value) === "";
 }
 /**
-* Is the value `undefined`, `null`, or a whitespace-only string?
+* Is the value `undefined`, `null`, or stringified as a whitespace-only string?
 * @param value Value to check
-* @returns `true` if the value is nullable or a whitespace-only string, otherwise `false`
+* @returns `true` if the value is nullable or matches a whitespace-only string, otherwise `false`
 */
 function isNullableOrWhitespace(value) {
 	return value == null || EXPRESSION_WHITESPACE.test(getString(value));
@@ -50,7 +90,7 @@ function isNullableOrWhitespace(value) {
 /**
 * Is the value a number or a number-like string?
 * @param value Value to check
-* @returns `true` if the value is a number or a parseable string, otherwise `false`
+* @returns `true` if the value is a number or a number-like string, otherwise `false`
 */
 function isNumerical(value) {
 	return isNumber(value) || typeof value === "string" && value.trim().length > 0 && !Number.isNaN(+value);
@@ -65,4 +105,4 @@ function isObject(value) {
 }
 const EXPRESSION_WHITESPACE = /^\s*$/;
 //#endregion
-export { isArrayOrPlainObject, isConstructor, isEmpty, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive, isTypedArray };
+export { isArrayOrPlainObject, isConstructor, isEmpty, isInstanceOf, isKey, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isPlainObject, isPrimitive, isTypedArray };

package/dist/string/index.d.mts

@@ -1,6 +1,8 @@
 import { getString, join, words } from "../internal/string.mjs";
 
 //#region src/string/index.d.ts
+declare function dedent(strings: TemplateStringsArray, ...values: unknown[]): string;
+declare function dedent(value: string): string;
 /**
  * Get a new UUID-string _(version 4)_
  * @returns UUID string
@@ -28,4 +30,4 @@ declare function trim(value: string): string;
  */
 declare function truncate(value: string, length: number, suffix?: string): string;
 //#endregion
-export { getString, getUuid, join, parse, trim, truncate, words };
+export { dedent, getString, getUuid, join, parse, trim, truncate, words };

package/dist/string/index.mjs

@@ -1,5 +1,30 @@
+import { isTemplateStringsArray } from "../internal/is.mjs";
 import { getString, join, words } from "../internal/string.mjs";
 //#region src/string/index.ts
+function dedent(value, ...values) {
+	let actual;
+	if (isTemplateStringsArray(value)) actual = interpolate(value, values);
+	else actual = value;
+	if (typeof actual !== "string") return "";
+	const lines = actual.split("\n");
+	const { length } = lines;
+	if (length === 1) return actual.trim();
+	const lastIndex = length - 1;
+	const lengths = [];
+	for (let index = 0; index < length; index += 1) {
+		const [, indentation] = /^(\s+)/.exec(lines[index]) ?? [];
+		if (indentation != null) lengths.push(indentation.length);
+	}
+	if (lengths.length === 0) return actual.trim();
+	const minimum = Math.min(...lengths);
+	const pattern = new RegExp(`^\\s{0,${minimum}}`);
+	let result = "";
+	for (let index = 0; index < length; index += 1) {
+		const line = lines[index];
+		result += line.replace(pattern, "") + (index === lastIndex ? "" : "\n");
+	}
+	return result.trim();
+}
 /**
 * Get a new UUID-string _(version 4)_
 * @returns UUID string
@@ -18,6 +43,12 @@ function getUuid() {
 		hex.substring(20, 32)
 	].join("-");
 }
+function interpolate(strings, values) {
+	const { length } = strings;
+	let interpolated = "";
+	for (let index = 0; index < length; index += 1) interpolated += `${strings[index]}${getString(values[index])}`;
+	return interpolated;
+}
 /**
 * Parse a JSON string into its proper value _(or `undefined` if it fails)_
 * @param value JSON string to parse
@@ -57,4 +88,4 @@ function truncate(value, length, suffix) {
 }
 const ZERO = "0";
 //#endregion
-export { getString, getUuid, join, parse, trim, truncate, words };
+export { dedent, getString, getUuid, join, parse, trim, truncate, words };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.176.0",
+	"version": "0.178.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"
@@ -233,7 +241,7 @@
 		"watch": "npx vite build --watch"
 	},
 	"devDependencies": {
-		"@oxlint/plugins": "^1.59",
+		"@oxlint/plugins": "^1.60",
 		"@types/node": "^25.6",
 		"@vitest/coverage-istanbul": "^4.1",
 		"eslint": "^10.2",
@@ -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

@@ -14,7 +14,9 @@ export * from './intersection';
 export * from './partition';
 export * from './position';
 export * from './push';
+export * from './reverse';
 export * from './select';
+export * from './single';
 export * from './slice';
 export * from './splice';
 export * from './to-set';