@oscarpalmer/atoms 0.217.0 → 0.219.0

package/dist/array/select.d.mts

@@ -1,190 +1,171 @@
-import { PlainObject } from "../models/index.mjs";
-import { ArrayMapKeyOrCallback, ArrayMapped, ArrayObjectKeysOf } from "../models/array/array.misc.model.mjs";
+import { ArrayFlattened } from "../models/array/array.misc.model.mjs";
 //#region src/array/select.d.ts
 /**
- * Get a filtered and mapped array of items
+ * Get a narrowed, mapped, and flattened 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 map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * _Available as `filterAndFlatMap`, `filterAndMap.flat`, and `select.flat`_
  *
- * @example
- * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id,
- *   2,
- *   item => item.name,
- * ); // => ['Bob']
- * ```
- */
-export declare function filterAndMap<Item, FilterCallback extends (item: Item, index: number, array: Item[]) => unknown, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>, map: Map): Array<ArrayMapped<Item, Map>>;
-/**
- * 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 map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * @param array Array to select from
+ * @param filter Type guard to filter and narrow down the items
+ * @param mapper Callback to map and flatten the narrowed items
+ * @returns Narrowed, mapped, and flattened array of items
  *
  * @example
  * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   'id',
- *   2,
- *   'name',
- * ); // => ['Bob']
+ * filterAndFlatMap(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2}, {id: 3, tags: ['c']}],
+ *   (item): item is {id: number; tags: string[]} => item.tags != null,
+ *   item => item.tags,
+ * ); // => ['a', 'b', 'c']
  * ```
  */
-export declare function filterAndMap<Item extends PlainObject, ItemKey extends keyof Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], filterKey: ItemKey, filterValue: Item[ItemKey], map: Map): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndFlatMap<Item, Narrowed extends Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed, mapper: (item: Narrowed, index: number, array: Item[]) => Mapped): Array<ArrayFlattened<Mapped>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a filtered, mapped, and flattened array of items
  *
- * @param array Array to search in
- * @param filter Filter callback to match items
- * @param map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * _Available as `filterAndFlatMap`, `filterAndMap.flat`, and `select.flat`_
+ *
+ * @param array Array to select from
+ * @param filter Callback to filter the items
+ * @param mapper Callback to map and flatten the filtered items
+ * @returns Filtered, mapped, and flattened array of items
  *
  * @example
  * ```typescript
- * select(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => item.id === 2,
- *   item => item.name,
- * ); // => ['Bob']
+ * filterAndFlatMap(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2, tags: ['c']}, {id: 3, tags: ['d', 'e']}],
+ *   item => item.id !== 2,
+ *   item => item.tags,
+ * ); // => ['a', 'b', 'd', 'e']
  * ```
  */
-export declare function filterAndMap<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, map: Map): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndFlatMap<Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, mapper: (item: Item, index: number, array: Item[]) => Mapped): Array<ArrayFlattened<Mapped>>;
 /**
- * Get a filtered and mapped array of items
+ * Get a narrowed and mapped array of items
  *
- * @param array Array to search in
- * @param item Item to match against
- * @param map Callback or key to map the matched items
- * @returns Filtered and mapped array of items
+ * _Available as `filterAndMap` and `select`_
+ *
+ * @param array Array to select from
+ * @param filter Type guard to filter and narrow down the items
+ * @param mapper Callback to map the narrowed items
+ * @returns Narrowed and mapped array of items
  *
  * @example
  * ```typescript
- * select(
- *   [1, 2, 3, 2, 1],
- *   3,
- *   value => value ** 2,
- * ); // => [9]
+ * filterAndMap(
+ *   [{id: 1, name: 'Alice'}, {id: 2}, {id: 3, name: 'Charlie'}],
+ *   (item): item is {id: number; name: string} => item.name != null,
+ *   item => item.name.toUpperCase(),
+ * ); // => ['ALICE', 'CHARLIE']
  * ```
  */
-export declare function filterAndMap<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], item: Item, map: Map): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndMap<Item, Narrowed extends Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed, mapper: (item: Narrowed, index: number, array: Item[]) => Mapped): Mapped[];
 /**
- * Get a mapped and filtered array of items
+ * Get a filtered and mapped array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `filterAndMap` and `select`_
  *
- * @param array Array to search in
- * @param map Callback or key to map the items
- * @param filterCallback Callback to get a mapped value's value for matching
- * @param filterValue Value to match against
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param filter Callback to filter the items
+ * @param mapper Callback to map the filtered items
+ * @returns Filtered and mapped array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
+ * filterAndMap(
  *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.id === 2,
  *   item => item.name,
- *   value => value.length,
- *   3,
  * ); // => ['Bob']
  * ```
  */
-export declare function mapAndFilter<Item, Map extends ArrayMapKeyOrCallback<Item>, FilterCallback extends (item: ArrayMapped<Item, Map>, index: number, array: Item[]) => unknown>(array: Item[], map: Map, filterCallback: FilterCallback, filterValue: ReturnType<FilterCallback>): Array<ArrayMapped<Item, Map>>;
+export declare function filterAndMap<Item, Mapped>(array: Item[], filter: (item: Item, index: number, array: Item[]) => boolean, mapper: (item: Item, index: number, array: Item[]) => Mapped): Mapped[];
 /**
- * Get a mapped and filtered array of items
+ * Get a mapped, flattened, and narrowed array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `flatMapAndFilter`, `mapAndFilter.flat`, and `reverseSelect.flat`_
  *
- * @param array Array to search in
- * @param map Callback to map the items
- * @param filterKey Key to get a mapped value's value for matching
- * @param filterValue Value to match against
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param mapper Callback to map and flatten the items
+ * @param filter Type guard to filter and narrow down the flattened items
+ * @returns Mapped, flattened, and narrowed array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
- *   item => ({label: item.name}),
- *   'label',
- *   'Bob',
- * ); // => [{label: 'Bob'}]
+ * flatMapAndFilter(
+ *   [{id: 1, values: [1, 'a']}, {id: 2, values: ['b', 2]}],
+ *   item => item.values,
+ *   (value): value is number => typeof value === 'number',
+ * ); // => [1, 2]
  * ```
  */
-export declare function mapAndFilter<Item, MapCallback extends (item: Item, index: number, array: Item[]) => PlainObject, ItemKey extends keyof ReturnType<MapCallback>>(array: Item[], map: MapCallback, filterKey: ItemKey, filterValue: ReturnType<MapCallback>[ItemKey]): Array<ReturnType<MapCallback>>;
+export declare function flatMapAndFilter<Item, Mapped, Narrowed extends ArrayFlattened<Mapped>>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: ArrayFlattened<Mapped>, index: number, array: Item[]) => item is Narrowed): Narrowed[];
 /**
- * Get a mapped and filtered array of items
+ * Get a mapped, flattened, and filtered array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `flatMapAndFilter`, `mapAndFilter.flat`, and `reverseSelect.flat`_
  *
- * @param array Array to search in
- * @param map Key to map the items
- * @param filterKey Key to get a mapped value's value for matching
- * @param filterValue Value to match against
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param mapper Callback to map and flatten the items
+ * @param filter Callback to filter the flattened items
+ * @returns Mapped, flattened, and filtered array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [{meta: {tag: 'a'}}, {meta: {tag: 'b'}}],
- *   'meta',
- *   'tag',
- *   'b',
- * ); // => [{tag: 'b'}]
+ * flatMapAndFilter(
+ *   [{id: 1, tags: ['a', 'b']}, {id: 2, tags: ['c']}, {id: 3, tags: ['b', 'd']}],
+ *   item => item.tags,
+ *   tag => tag !== 'b',
+ * ); // => ['a', 'c', 'd']
  * ```
  */
-export declare function mapAndFilter<Item, MapKey extends ArrayObjectKeysOf<Item>, ItemKey extends keyof Item[MapKey]>(array: Item[], map: MapKey, filterKey: ItemKey, filterValue: Item[MapKey][ItemKey]): Array<Item[MapKey]>;
+export declare function flatMapAndFilter<Item, Mapped>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: ArrayFlattened<Mapped>, index: number, array: Item[]) => boolean): Array<ArrayFlattened<Mapped>>;
 /**
- * Get a mapped and filtered array of items
+ * Get a mapped and narrowed array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `mapAndFilter`, `reverseSelect`, `filterAndMap.reverse`, and `select.reverse`_
  *
- * @param array Array to search in
- * @param map Callback or key to map the items
- * @param filter Filter callback to match mapped values
- * @returns Mapped and filtered array of items
+ * @param array Array to select from
+ * @param mapper Callback to map the items
+ * @param filter Type guard to filter and narrow down the mapped items
+ * @returns Mapped and narrowed array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ * mapAndFilter(
+ *   [{id: 1, name: 'Alice'}, {id: 2}, {id: 3, name: 'Charlie'}],
  *   item => item.name,
- *   value => value.startsWith('B'),
- * ); // => ['Bob']
+ *   (name): name is string => name != null,
+ * ); // => ['Alice', 'Charlie']
  * ```
  */
-export declare function mapAndFilter<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], map: Map, filter: (item: ArrayMapped<Item, Map>, index: number, array: Item[]) => boolean): Array<ArrayMapped<Item, Map>>;
+export declare function mapAndFilter<Item, Mapped, Narrowed extends Mapped>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: Mapped, index: number, array: Item[]) => item is Narrowed): Narrowed[];
 /**
  * Get a mapped and filtered array of items
  *
- * _Available as `reverseSelect`_ and `select.reverse`_
+ * _Available as `mapAndFilter`, `reverseSelect`, `filterAndMap.reverse`, and `select.reverse`_
  *
- * @param array Array to search in
- * @param map Callback or key to map the items
- * @param value Mapped value to match against
+ * @param array Array to select from
+ * @param mapper Callback to map the items
+ * @param filter Callback to filter the mapped items
  * @returns Mapped and filtered array of items
  *
  * @example
  * ```typescript
- * reverseSelect(
- *   [1, 2, 3, 2, 1],
- *   value => value ** 2,
- *   4,
- * ); // => [4, 4]
+ * mapAndFilter(
+ *   [{id: 1, name: 'Alice'}, {id: 2, name: 'Bob'}, {id: 3, name: 'Charlie'}],
+ *   item => item.name,
+ *   name => name.length > 3,
+ * ); // => ['Alice', 'Charlie']
  * ```
  */
-export declare function mapAndFilter<Item, Map extends ArrayMapKeyOrCallback<Item>>(array: Item[], map: Map, value: ArrayMapped<Item, Map>): Array<ArrayMapped<Item, Map>>;
+export declare function mapAndFilter<Item, Mapped>(array: Item[], mapper: (item: Item, index: number, array: Item[]) => Mapped, filter: (item: Mapped, index: number, array: Item[]) => boolean): Mapped[];
 export declare namespace filterAndMap {
+  export var flat: typeof filterAndFlatMap;
   export var reverse: typeof mapAndFilter;
 }
+export declare namespace mapAndFilter {
+  export var flat: typeof flatMapAndFilter;
+}
 //#endregion
 export { filterAndMap as select, mapAndFilter as reverseSelect };

package/dist/array/select.mjs

@@ -1,23 +1,27 @@
 import "../models/array/array.find.model.mjs";
 import { findValues } from "../internal/array/find.mjs";
 //#region src/array/select.ts
-function filterAndMap(array, ...parameters) {
-	return selectValues(array, parameters);
+function filterAndFlatMap(array, filter, mapper) {
+	return selectValues(array, filter, mapper, true, false);
 }
-function mapAndFilter(array, ...parameters) {
-	const mapper = parameters.shift();
-	return findValues("all", array, parameters, {
-		callback: mapper,
-		reverse: true
-	}).matched;
+function filterAndMap(array, filter, mapper) {
+	return selectValues(array, filter, mapper, false, false);
 }
-function selectValues(array, parameters) {
-	const mapper = parameters.pop();
-	return findValues("all", array, parameters, {
-		callback: mapper,
-		reverse: false
-	}).matched;
+function flatMapAndFilter(array, mapper, filter) {
+	return selectValues(array, filter, mapper, true, true);
 }
+function mapAndFilter(array, mapper, filter) {
+	return selectValues(array, filter, mapper, false, true);
+}
+function selectValues(array, filter, mapper, flat, reverse) {
+	return findValues("all", array, [filter], { map: {
+		flat,
+		reverse,
+		callback: mapper
+	} }).matched;
+}
+filterAndMap.flat = filterAndFlatMap;
 filterAndMap.reverse = mapAndFilter;
+mapAndFilter.flat = flatMapAndFilter;
 //#endregion
-export { filterAndMap, filterAndMap as select, mapAndFilter, mapAndFilter as reverseSelect };
+export { filterAndFlatMap, filterAndMap, filterAndMap as select, flatMapAndFilter, mapAndFilter, mapAndFilter as reverseSelect };

package/dist/array/single.d.mts

@@ -40,6 +40,28 @@ export declare function single<Item, Callback extends (item: Item, index: number
  * ```
  */
 export declare function single<Item extends PlainObject, ItemKey extends keyof Item>(array: Item[], key: ItemKey, value: Item[ItemKey]): Item | undefined;
+/**
+ * Get the _only_ narrowed item matching the filter
+ *
+ * _Throws an error if multiple items match the filter_
+ *
+ * @param array Array to search in
+ * @param filter Type guard to match and narrow down the items
+ * @returns Only narrowed item that matches the filter, or `undefined` if no match is found
+ *
+ * @example
+ * ```typescript
+ * single(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: number} => typeof item.value === 'number',
+ * ); // => {id: 1, value: 10}
+ * single(
+ *   [{id: 1, value: 10}, {id: 2, value: 'a'}, {id: 3, value: 'b'}],
+ *   (item): item is {id: number; value: string} => typeof item.value === 'string',
+ * ); // => throws an error as there are two matches
+ * ```
+ */
+export declare function single<Item, Narrowed extends Item>(array: Item[], filter: (item: Item, index: number, array: Item[]) => item is Narrowed): Narrowed | undefined;
 /**
  * Get the _only_ item matching the filter
  *

package/dist/array/single.mjs

@@ -2,7 +2,7 @@ import "../models/array/array.find.model.mjs";
 import { findValues } from "../internal/array/find.mjs";
 //#region src/array/single.ts
 function single(array, ...parameters) {
-	const { matched } = findValues("all", array, parameters);
+	const { matched } = findValues("all", array, parameters, { limit: 2 });
 	if (matched.length > 1) throw new Error(SINGLE_MESSAGE);
 	return matched[0];
 }

package/dist/array/slice.mjs

@@ -8,34 +8,47 @@ function extract(type, array, first, second) {
 	if (!Array.isArray(array)) return [];
 	const { length } = array;
 	if (length === 0) return [];
-	const isTake = type === ARRAY_SLICE_TAKE;
-	if (typeof first === "number") {
-		if (Math.abs(first) >= length) return isTake ? array.slice() : [];
-		if (first === 0) return isTake ? [] : array.slice();
-		if (isTake) return first >= 0 ? array.slice(0, first) : array.slice(array.length + first);
-		return first >= 0 ? array.slice(first) : array.slice(0, array.length + first);
-	}
-	const callbacks = second == null ? getArrayCallbacks(first) : getArrayCallbacks(void 0, void 0, first);
+	const take = type === ARRAY_SLICE_TAKE;
+	return typeof first === "number" ? getSlice(array, length, first, take) : extractSlice(array, length, first, second, take);
+}
+function extractSlice(array, length, first, second, take) {
+	const callbacks = getCallbacks(first, second);
+	if (callbacks?.bool == null && callbacks?.value == null) return take ? array.slice() : [];
 	const isBoolean = callbacks?.bool != null;
-	if (callbacks?.bool == null && callbacks?.value == null) return isTake ? array.slice() : [];
 	const extracted = [];
 	let push = false;
 	for (let index = 0; index < length; index += 1) {
 		const item = array[index];
-		const matches = isBoolean ? callbacks.bool(item, index, array) : Object.is(callbacks.value(item, index, array), second);
-		if (isTake) {
-			if (isBoolean ? !matches : matches) break;
+		const matches = isMatch(item, index, array, callbacks, second, isBoolean);
+		const reached = isBoolean ? !matches : matches;
+		if (take && reached) break;
+		if (push || take) {
 			extracted.push(item);
 			continue;
 		}
-		if (push) extracted.push(item);
-		else if (isBoolean ? !matches : matches) {
+		if (reached) {
 			push = true;
 			if (isBoolean) extracted.push(item);
 		}
 	}
 	return extracted;
 }
+function getCallbacks(first, second) {
+	let callbacks;
+	if (second == null) callbacks = getArrayCallbacks(first);
+	else callbacks = getArrayCallbacks(void 0, void 0, first);
+	return callbacks;
+}
+function getSlice(array, length, amount, take) {
+	if (Math.abs(amount) >= length) return take ? array.slice() : [];
+	if (amount === 0) return take ? [] : array.slice();
+	if (take) return amount >= 0 ? array.slice(0, amount) : array.slice(length + amount);
+	return amount >= 0 ? array.slice(amount) : array.slice(0, length + amount);
+}
+function isMatch(item, index, array, callbacks, second, isBoolean) {
+	if (isBoolean) return callbacks.bool(item, index, array);
+	return Object.is(callbacks.value(item, index, array), second);
+}
 function slice(array, first, second) {
 	if (!Array.isArray(array) || array.length === 0) return [];
 	const firstIsNumber = typeof first === "number";

package/dist/array/sort.d.mts

@@ -13,6 +13,11 @@ declare function Sorter(this: any, sorters: SortHandler[]): void;
  * @param sorters Sorters to use to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Index for item
+ *
+ * @example
+ * ```typescript
+ * getSortedIndex([1, 3, 2], 2, [{key: 'value', direction: 'asc'}]); // => 1
+ * ```
  */
 export declare function getSortedIndex<Item>(array: Item[], item: Item, sorters: Array<ArraySorter<Item>>, descending?: boolean): number;
 /**
@@ -27,6 +32,11 @@ export declare function getSortedIndex<Item>(array: Item[], item: Item, sorters:
  * @param sorter Sorter to use to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Index for item
+ *
+ * @example
+ * ```typescript
+ * getSortedIndex([1, 3, 2], 2, {key: 'value', direction: 'asc'}); // => 1
+ * ```
  */
 export declare function getSortedIndex<Item>(array: Item[], item: Item, sorter: ArraySorter<Item>, descending?: boolean): number;
 /**
@@ -40,6 +50,11 @@ export declare function getSortedIndex<Item>(array: Item[], item: Item, sorter:
  * @param item Item to get the index for
  * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns Index for item
+ *
+ * @example
+ * ```typescript
+ * getSortedIndex([1, 3, 2], 2); // => 1
+ * ```
  */
 export declare function getSortedIndex<Item>(array: Item[], item: Item, descending?: boolean): number;
 /**
@@ -80,6 +95,12 @@ export declare function initializeSorter<Item>(descending?: boolean): Sorter<Ite
  * @param sorters Sorters to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns `true` if sorted, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isSorted([1, 2, 3], [{key: 'value', direction: 'asc'}]); // => true
+ * isSorted([3, 2, 1], [{key: 'value', direction: 'asc'}]); // => false
+ * ```
  */
 export declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): boolean;
 /**
@@ -91,6 +112,12 @@ export declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter
  * @param sorter Sorter to determine sorting
  * @param descending Sorted in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns `true` if sorted, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isSorted([1, 2, 3], {key: 'value', direction: 'asc'}); // => true
+ * isSorted([3, 2, 1], {key: 'value', direction: 'asc'}); // => false
+ * ```
  */
 export declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): boolean;
 /**
@@ -101,6 +128,12 @@ export declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>,
  * @param array Array to check
  * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns `true` if sorted, otherwise `false`
+ *
+ * @example
+ * ```typescript
+ * isSorted([1, 2, 3]); // => true
+ * isSorted([3, 2, 1]); // => false
+ * ```
  */
 export declare function isSorted<Item>(array: Item[], descending?: boolean): boolean;
 /**
@@ -127,6 +160,14 @@ export declare function sort<Item>(array: Item[], comparator: (first: Item, seco
  * @param sorters Sorters to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort(
+ *   [{id: 3}, {id: 1}, {id: 2}],
+ *   [{key: 'id', direction: 'asc'}],
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 export declare function sort<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): Item[];
 /**
@@ -136,6 +177,14 @@ export declare function sort<Item>(array: Item[], sorters: Array<ArraySorter<Ite
  * @param sorter Sorter to use for sorting
  * @param descending Sort in descending order? _(defaults to `false`; overridden by individual sorters)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort(
+ *   [{id: 3}, {id: 1}, {id: 2}],
+ *   {key: 'id', direction: 'asc'},
+ * ); // => [{id: 1}, {id: 2}, {id: 3}]
+ * ```
  */
 export declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): Item[];
 /**
@@ -144,6 +193,11 @@ export declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, des
  * @param array Array to sort
  * @param descending Sort in descending order? _(defaults to `false`)_
  * @returns Sorted array
+ *
+ * @example
+ * ```typescript
+ * sort([3, 1, 2]); // => [1, 2, 3]
+ * ```
  */
 export declare function sort<Item>(array: Item[], descending?: boolean): Item[];
 export declare namespace sort {

package/dist/array/sort.mjs

@@ -1,5 +1,6 @@
 import { isPlainObject } from "../internal/is.mjs";
 import { floor, round } from "../internal/math/misc.mjs";
+import { min } from "../internal/math/aggregate.mjs";
 import { compare } from "../internal/value/compare.mjs";
 import { SORTER_SYMBOL, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, arrayModifiers } from "../models/array/array.sort.model.mjs";
 //#region src/array/sort.ts
@@ -106,7 +107,7 @@ function isSortedArray(array) {
 	let offset = 0;
 	if (length >= 100) {
 		offset = round(length / 10);
-		offset = offset > 100 ? 100 : offset;
+		offset = min([offset, 100]);
 		for (let index = 0; index < offset; index += 1) {
 			const [firstItem, firstOffset] = [array[index], array[index + 1]];
 			const [secondItem, secondOffset] = [array[length - index - 2], array[length - index - 1]];

package/dist/color/misc/get.mjs

@@ -5,7 +5,9 @@ import { getColorFromState, getColorState } from "./state.mjs";
 import { color } from "../instance.mjs";
 //#region src/color/misc/get.ts
 function getClampedValue(value, minimum, maximum, rounding) {
-	return typeof value === "number" && !Number.isNaN(value) ? clamp(rounding ?? false ? round(value) : value, minimum, maximum) : minimum;
+	if (typeof value !== "number" || Number.isNaN(value)) return minimum;
+	const actual = rounding ?? false ? round(value) : value;
+	return clamp(actual, minimum, maximum);
 }
 function getForegroundColor(value, hex) {
 	const { blue, green, red } = getColorFromState(getColorState(value), COLOR_TYPE.rgb);

package/dist/color/space/hex.d.mts

@@ -11,6 +11,14 @@ export declare function getHexaColor(this: InternalColor): string;
  * @param value Value to normalize
  * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
  * @returns Normalized hex color
+ *
+ * @example
+ * ```typescript
+ * getNormalizedHex('#abc'); // => '#aabbcc'
+ * getNormalizedHex('#abc', true); // => '#aabbccff'
+ * getNormalizedHex(123); // => '#000000'
+ * getNormalizedHex(123, true); // => '#000000ff'
+ * ```
  */
 export declare function getNormalizedHex(value: unknown, alpha?: boolean): string;
 /**

package/dist/color/space/hex.mjs

@@ -44,9 +44,17 @@ function getHexaColor() {
 * @param value Value to normalize
 * @param alpha Include alpha channel _(opacity)_? _(defaults to `false`)_
 * @returns Normalized hex color
+*
+* @example
+* ```typescript
+* getNormalizedHex('#abc'); // => '#aabbcc'
+* getNormalizedHex('#abc', true); // => '#aabbccff'
+* getNormalizedHex(123); // => '#000000'
+* getNormalizedHex(123, true); // => '#000000ff'
+* ```
 */
 function getNormalizedHex(value, alpha) {
-	const includeAlpha = alpha ?? false;
+	const includeAlpha = alpha === true;
 	if (!isHexColor(value)) return `${COLOR_DEFAULTS.hexBlack}${includeAlpha ? COLOR_ALPHA.fullHexLong : ""}`;
 	const normalized = value.replace(COLOR_EXPRESSION.prefix, "");
 	if (normalized.length < COLOR_LENGTHS.hexLong) {

package/dist/function/retry.d.mts

@@ -20,7 +20,7 @@ declare function asyncRetry<Callback extends GenericAsyncCallback>(callback: Cal
  * @param options Retry options
  * @returns Callback result
  */
-declare function asyncRetry<Callback extends GenericCallback>(callback: Callback, options?: RetryOptions): Promise<ReturnType<Callback>>;
+declare function asyncRetry<Callback extends GenericAsyncCallback>(callback: Callback, options?: RetryOptions): Promise<ReturnType<Callback>>;
 /**
  * Retry a callback a specified number of times
  *

package/dist/function/retry.mjs

@@ -18,8 +18,11 @@ async function asyncRetry(callback, options) {
 	if (typeof callback !== "function") throw new TypeError(RETRY_MESSAGE_EXPECTATION);
 	async function handle() {
 		const result = await asyncAttempt(async () => callback());
-		if (result.ok) resolver(result.value);
-		else if (attempts >= times || !when(result.error)) rejector(new RetryError(RETRY_MESSAGE_FAILED, result.error));
+		if (result.ok) {
+			resolver(result.value);
+			return;
+		}
+		if (attempts >= times || !when(result.error)) rejector(new RetryError(RETRY_MESSAGE_FAILED, result.error));
 		else {
 			attempts += 1;
 			limiter.run();