@oscarpalmer/atoms 0.173.3 → 0.175.0

package/dist/array/sort.d.mts

@@ -65,7 +65,61 @@ type ComparisonSorter<Item> = (first: Item, second: Item) => number;
  * Direction to sort by
  */
 type SortDirection = 'ascending' | 'descending';
-type Sorter<Item> = (array: Item[]) => Item[];
+type Sorter<Item> = {
+  /**
+   * Sort an array of items
+   * @param array Array to sort
+   * @returns Sorted array
+   */
+  (array: Item[]): Item[];
+  /**
+   * Get the index for an item _(to be inserted into an array of items)_
+   *
+   * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+   * @param array Array to get the index from
+   * @param item Item to get the index for
+   * @returns Index for item
+   */
+  index(array: Item[], item: Item): number;
+  /**
+   * Is the array sorted?
+   * @param array Array to check
+   * @returns `true` if sorted, otherwise `false`
+   */
+  is(array: Item[]): boolean;
+};
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on sorters _(and an optional default direction)_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @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
+ */
+declare function getIndex<Item>(array: Item[], item: Item, sorters: Array<ArraySorter<Item>>, descending?: boolean): number;
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on a sorter _(and an optional default direction)_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @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
+ */
+declare function getIndex<Item>(array: Item[], item: Item, sorter: ArraySorter<Item>, descending?: boolean): number;
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on an optional default direction_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @param descending Sorted in descending order? _(defaults to `false`)_
+ * @returns Index for item
+ */
+declare function getIndex<Item>(array: Item[], item: Item, descending?: boolean): number;
 /**
  * Initialize a sort handler with sorters _(and an optional default direction)_
  * @param sorters Sorters to use for sorting
@@ -86,6 +140,29 @@ declare function initializeSort<Item>(sorter: ArraySorter<Item>, descending?: bo
  * @returns Sort handler
  */
 declare function initializeSort<Item>(descending?: boolean): Sorter<Item>;
+/**
+ * Is the array sorted according to the sorters _(and the optional default direction)_?
+ * @param array Array to check
+ * @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`
+ */
+declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): boolean;
+/**
+ * Is the array sorted according to the sorter _(and the optional default direction)_?
+ * @param array Array to check
+ * @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`
+ */
+declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): boolean;
+/**
+ * Is the array sorted?
+ * @param array Array to check
+ * @param descending Sorted in descending order? _(defaults to `false`)_
+ * @returns `true` if sorted, otherwise `false`
+ */
+declare function isSorted<Item>(array: Item[], descending?: boolean): boolean;
 /**
  * Sort an array of items, using multiple sorters to sort by specific values
  * @param array Array to sort
@@ -110,7 +187,9 @@ declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending
  */
 declare function sort<Item>(array: Item[], descending?: boolean): Item[];
 declare namespace sort {
+  var index: typeof getIndex;
   var initialize: typeof initializeSort;
+  var is: typeof isSorted;
 }
 declare const SORT_DIRECTION_ASCENDING: SortDirection;
 declare const SORT_DIRECTION_DESCENDING: SortDirection;

package/dist/array/sort.mjs

@@ -9,6 +9,18 @@ function getComparisonSorter(callback, modifier) {
 		identifier: String(callback)
 	};
 }
+function getComparisonValue(first, second, sorters, length) {
+	for (let index = 0; index < length; index += 1) {
+		const sorter = sorters[index];
+		const values = [sorter.get ? sorter.value(first) : first, sorter.get ? sorter.value(second) : second];
+		const comparison = (sorter.compare?.complex?.(first, values[0], second, values[1]) ?? sorter.compare?.simple?.(values[0], values[1]) ?? compare(values[0], values[1])) * sorter.modifier;
+		if (comparison !== 0) return comparison;
+	}
+	return 0;
+}
+function getIndex(array, item, first, second) {
+	return getSortedIndex(array, item, getSorters(first, getModifier(first, second)));
+}
 function getModifier(first, second) {
 	return modifiers[first === true || second === true ? SORT_DIRECTION_DESCENDING : SORT_DIRECTION_ASCENDING];
 }
@@ -22,6 +34,22 @@ function getObjectSorter(obj, modifier) {
 	if (sorter != null && typeof obj.direction === "string") sorter.modifier = modifiers[obj.direction] ?? modifier;
 	return sorter;
 }
+function getSortedIndex(array, item, sorters) {
+	if (!Array.isArray(array)) return -1;
+	const { length } = array;
+	if (length === 0) return 0;
+	const sortersLength = sorters.length;
+	if (getComparisonValue(item, array[0], sorters, sortersLength) < 0) return 0;
+	if (getComparisonValue(item, array[length - 1], sorters, sortersLength) >= 0) return length;
+	let low = 0;
+	let high = length - 1;
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+		if (getComparisonValue(item, array[mid], sorters, sortersLength) < 0) high = mid - 1;
+		else low = mid + 1;
+	}
+	return low;
+}
 function getSorter(value, modifier) {
 	switch (true) {
 		case typeof value === "function": return getComparisonSorter(value, modifier);
@@ -39,6 +67,11 @@ function getSorters(value, modifier) {
 		const sorter = getSorter(item, modifier);
 		if (sorter != null) sorters.push(sorter);
 	}
+	if (sorters.length === 0) return [{
+		modifier,
+		get: false,
+		identifier: "default"
+	}];
 	return sorters.filter((value, index, array) => array.findIndex((next) => next.identifier === value.identifier) === index);
 }
 function getValueSorter(value, modifier) {
@@ -50,30 +83,52 @@ function getValueSorter(value, modifier) {
 	};
 }
 function initializeSort(first, second) {
-	const modifier = getModifier(first, second);
-	const sorters = getSorters(first, modifier);
-	return (array) => work(array, sorters, modifier);
+	const sorters = getSorters(first, getModifier(first, second));
+	const sorter = (array) => sortArray(array, sorters);
+	sorter.index = (array, item) => getSortedIndex(array, item, sorters);
+	sorter.is = (array) => isSortedArray(array, sorters);
+	return sorter;
+}
+function isSorted(array, first, second) {
+	return isSortedArray(array, getSorters(first, getModifier(first, second)));
+}
+function isSortedArray(array, sorters) {
+	if (!Array.isArray(array)) return false;
+	const { length } = array;
+	if (length < 2) return true;
+	const sortersLength = sorters.length;
+	let offset = 0;
+	if (length >= ARRAY_THRESHOLD) {
+		offset = Math.round(length / ARRAY_PEEK_PERCENTAGE);
+		offset = offset > ARRAY_THRESHOLD ? ARRAY_THRESHOLD : offset;
+		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]];
+			const [firstComparison, secondComparison] = [getComparisonValue(firstItem, firstOffset, sorters, sortersLength), getComparisonValue(secondItem, secondOffset, sorters, sortersLength)];
+			if (firstComparison > 0 || secondComparison > 0) return false;
+		}
+	}
+	const end = length - offset - 1;
+	for (let index = offset; index < end; index += 1) {
+		const first = array[index];
+		const second = array[index + 1];
+		if (getComparisonValue(first, second, sorters, sortersLength) > 0) return false;
+	}
+	return true;
 }
 function sort(array, first, second) {
-	const modifier = getModifier(first, second);
-	return work(array, getSorters(first, modifier), modifier);
+	return sortArray(array, getSorters(first, getModifier(first, second)));
 }
-function work(array, sorters, modifier) {
+function sortArray(array, sorters) {
 	if (!Array.isArray(array)) return [];
-	if (array.length < 2) return array;
 	const { length } = sorters;
-	if (length === 0) return array.sort((first, second) => compare(first, second) * modifier);
-	return array.sort((first, second) => {
-		for (let index = 0; index < length; index += 1) {
-			const sorter = sorters[index];
-			const values = [sorter.get ? sorter.value(first) : first, sorter.get ? sorter.value(second) : second];
-			const comparison = (sorter.compare?.complex?.(first, values[0], second, values[1]) ?? sorter.compare?.simple?.(values[0], values[1]) ?? compare(values[0], values[1])) * sorter.modifier;
-			if (comparison !== 0) return comparison;
-		}
-		return 0;
-	});
+	return array.length > 1 ? array.sort((first, second) => getComparisonValue(first, second, sorters, length)) : array;
 }
+sort.index = getIndex;
 sort.initialize = initializeSort;
+sort.is = isSorted;
+const ARRAY_PEEK_PERCENTAGE = 10;
+const ARRAY_THRESHOLD = 100;
 const SORT_DIRECTION_ASCENDING = "ascending";
 const SORT_DIRECTION_DESCENDING = "descending";
 const modifiers = {

package/dist/index.d.mts

@@ -1166,7 +1166,61 @@ type ComparisonSorter<Item> = (first: Item, second: Item) => number;
  * Direction to sort by
  */
 type SortDirection = 'ascending' | 'descending';
-type Sorter<Item> = (array: Item[]) => Item[];
+type Sorter<Item> = {
+  /**
+   * Sort an array of items
+   * @param array Array to sort
+   * @returns Sorted array
+   */
+  (array: Item[]): Item[];
+  /**
+   * Get the index for an item _(to be inserted into an array of items)_
+   *
+   * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+   * @param array Array to get the index from
+   * @param item Item to get the index for
+   * @returns Index for item
+   */
+  index(array: Item[], item: Item): number;
+  /**
+   * Is the array sorted?
+   * @param array Array to check
+   * @returns `true` if sorted, otherwise `false`
+   */
+  is(array: Item[]): boolean;
+};
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on sorters _(and an optional default direction)_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @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
+ */
+declare function getIndex<Item>(array: Item[], item: Item, sorters: Array<ArraySorter<Item>>, descending?: boolean): number;
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on a sorter _(and an optional default direction)_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @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
+ */
+declare function getIndex<Item>(array: Item[], item: Item, sorter: ArraySorter<Item>, descending?: boolean): number;
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on an optional default direction_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @param descending Sorted in descending order? _(defaults to `false`)_
+ * @returns Index for item
+ */
+declare function getIndex<Item>(array: Item[], item: Item, descending?: boolean): number;
 /**
  * Initialize a sort handler with sorters _(and an optional default direction)_
  * @param sorters Sorters to use for sorting
@@ -1187,6 +1241,29 @@ declare function initializeSort<Item>(sorter: ArraySorter<Item>, descending?: bo
  * @returns Sort handler
  */
 declare function initializeSort<Item>(descending?: boolean): Sorter<Item>;
+/**
+ * Is the array sorted according to the sorters _(and the optional default direction)_?
+ * @param array Array to check
+ * @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`
+ */
+declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>, descending?: boolean): boolean;
+/**
+ * Is the array sorted according to the sorter _(and the optional default direction)_?
+ * @param array Array to check
+ * @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`
+ */
+declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): boolean;
+/**
+ * Is the array sorted?
+ * @param array Array to check
+ * @param descending Sorted in descending order? _(defaults to `false`)_
+ * @returns `true` if sorted, otherwise `false`
+ */
+declare function isSorted<Item>(array: Item[], descending?: boolean): boolean;
 /**
  * Sort an array of items, using multiple sorters to sort by specific values
  * @param array Array to sort
@@ -1211,7 +1288,9 @@ declare function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending
  */
 declare function sort<Item>(array: Item[], descending?: boolean): Item[];
 declare namespace sort {
+  var index: typeof getIndex;
   var initialize: typeof initializeSort;
+  var is: typeof isSorted;
 }
 declare const SORT_DIRECTION_ASCENDING: SortDirection;
 declare const SORT_DIRECTION_DESCENDING: SortDirection;

package/dist/index.mjs

@@ -869,26 +869,11 @@ compare.handlers = getCompareHandlers(compare, {
 });
 compare.register = registerComparator;
 compare.unregister = unregisterComparator;
-/**
-* Register a custom comparison handler for a class
-* @param constructor Class constructor
-* @param handler Method name or comparison function _(defaults to `compare`)_
-*/
-function registerComparator(constructor, handler) {
-	compare.handlers.register(constructor, handler);
-}
-/**
-* Unregister a custom comparison handler for a class
-* @param constructor Class constructor
-*/
-function unregisterComparator(constructor) {
-	compare.handlers.unregister(constructor);
-}
 function compareNumbers(first, second) {
-	const firstNumber = Number(first);
-	const secondNumber = Number(second);
-	if (Object.is(firstNumber, secondNumber)) return 0;
-	return firstNumber > secondNumber ? 1 : -1;
+	if (Object.is(first, second)) return 0;
+	if (Number.isNaN(first)) return -1;
+	if (Number.isNaN(second)) return 1;
+	return first > second ? 1 : -1;
 }
 function compareSymbols(first, second) {
 	return getString(first.description ?? first).localeCompare(getString(second.description ?? second));
@@ -903,9 +888,24 @@ function getComparisonParts(value) {
 	if (Array.isArray(value)) return value;
 	return typeof value === "object" ? [value] : words(getString(value));
 }
+/**
+* Register a custom comparison handler for a class
+* @param constructor Class constructor
+* @param handler Method name or comparison function _(defaults to `compare`)_
+*/
+function registerComparator(constructor, handler) {
+	compare.handlers.register(constructor, handler);
+}
+/**
+* Unregister a custom comparison handler for a class
+* @param constructor Class constructor
+*/
+function unregisterComparator(constructor) {
+	compare.handlers.unregister(constructor);
+}
 const comparators = {
 	bigint: compareNumbers,
-	boolean: compareNumbers,
+	boolean: (first, second) => compareNumbers(first ? 1 : 0, second ? 1 : 0),
 	number: compareNumbers,
 	symbol: compareSymbols
 };
@@ -919,6 +919,18 @@ function getComparisonSorter(callback, modifier) {
 		identifier: String(callback)
 	};
 }
+function getComparisonValue(first, second, sorters, length) {
+	for (let index = 0; index < length; index += 1) {
+		const sorter = sorters[index];
+		const values = [sorter.get ? sorter.value(first) : first, sorter.get ? sorter.value(second) : second];
+		const comparison = (sorter.compare?.complex?.(first, values[0], second, values[1]) ?? sorter.compare?.simple?.(values[0], values[1]) ?? compare(values[0], values[1])) * sorter.modifier;
+		if (comparison !== 0) return comparison;
+	}
+	return 0;
+}
+function getIndex(array, item, first, second) {
+	return getSortedIndex(array, item, getSorters(first, getModifier(first, second)));
+}
 function getModifier(first, second) {
 	return modifiers[first === true || second === true ? SORT_DIRECTION_DESCENDING : SORT_DIRECTION_ASCENDING];
 }
@@ -932,6 +944,22 @@ function getObjectSorter(obj, modifier) {
 	if (sorter != null && typeof obj.direction === "string") sorter.modifier = modifiers[obj.direction] ?? modifier;
 	return sorter;
 }
+function getSortedIndex(array, item, sorters) {
+	if (!Array.isArray(array)) return -1;
+	const { length } = array;
+	if (length === 0) return 0;
+	const sortersLength = sorters.length;
+	if (getComparisonValue(item, array[0], sorters, sortersLength) < 0) return 0;
+	if (getComparisonValue(item, array[length - 1], sorters, sortersLength) >= 0) return length;
+	let low = 0;
+	let high = length - 1;
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+		if (getComparisonValue(item, array[mid], sorters, sortersLength) < 0) high = mid - 1;
+		else low = mid + 1;
+	}
+	return low;
+}
 function getSorter(value, modifier) {
 	switch (true) {
 		case typeof value === "function": return getComparisonSorter(value, modifier);
@@ -949,6 +977,11 @@ function getSorters(value, modifier) {
 		const sorter = getSorter(item, modifier);
 		if (sorter != null) sorters.push(sorter);
 	}
+	if (sorters.length === 0) return [{
+		modifier,
+		get: false,
+		identifier: "default"
+	}];
 	return sorters.filter((value, index, array) => array.findIndex((next) => next.identifier === value.identifier) === index);
 }
 function getValueSorter(value, modifier) {
@@ -960,30 +993,52 @@ function getValueSorter(value, modifier) {
 	};
 }
 function initializeSort(first, second) {
-	const modifier = getModifier(first, second);
-	const sorters = getSorters(first, modifier);
-	return (array) => work$1(array, sorters, modifier);
+	const sorters = getSorters(first, getModifier(first, second));
+	const sorter = (array) => sortArray(array, sorters);
+	sorter.index = (array, item) => getSortedIndex(array, item, sorters);
+	sorter.is = (array) => isSortedArray(array, sorters);
+	return sorter;
+}
+function isSorted(array, first, second) {
+	return isSortedArray(array, getSorters(first, getModifier(first, second)));
+}
+function isSortedArray(array, sorters) {
+	if (!Array.isArray(array)) return false;
+	const { length } = array;
+	if (length < 2) return true;
+	const sortersLength = sorters.length;
+	let offset = 0;
+	if (length >= ARRAY_THRESHOLD$1) {
+		offset = Math.round(length / ARRAY_PEEK_PERCENTAGE$1);
+		offset = offset > ARRAY_THRESHOLD$1 ? ARRAY_THRESHOLD$1 : offset;
+		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]];
+			const [firstComparison, secondComparison] = [getComparisonValue(firstItem, firstOffset, sorters, sortersLength), getComparisonValue(secondItem, secondOffset, sorters, sortersLength)];
+			if (firstComparison > 0 || secondComparison > 0) return false;
+		}
+	}
+	const end = length - offset - 1;
+	for (let index = offset; index < end; index += 1) {
+		const first = array[index];
+		const second = array[index + 1];
+		if (getComparisonValue(first, second, sorters, sortersLength) > 0) return false;
+	}
+	return true;
 }
 function sort(array, first, second) {
-	const modifier = getModifier(first, second);
-	return work$1(array, getSorters(first, modifier), modifier);
+	return sortArray(array, getSorters(first, getModifier(first, second)));
 }
-function work$1(array, sorters, modifier) {
+function sortArray(array, sorters) {
 	if (!Array.isArray(array)) return [];
-	if (array.length < 2) return array;
 	const { length } = sorters;
-	if (length === 0) return array.sort((first, second) => compare(first, second) * modifier);
-	return array.sort((first, second) => {
-		for (let index = 0; index < length; index += 1) {
-			const sorter = sorters[index];
-			const values = [sorter.get ? sorter.value(first) : first, sorter.get ? sorter.value(second) : second];
-			const comparison = (sorter.compare?.complex?.(first, values[0], second, values[1]) ?? sorter.compare?.simple?.(values[0], values[1]) ?? compare(values[0], values[1])) * sorter.modifier;
-			if (comparison !== 0) return comparison;
-		}
-		return 0;
-	});
+	return array.length > 1 ? array.sort((first, second) => getComparisonValue(first, second, sorters, length)) : array;
 }
+sort.index = getIndex;
 sort.initialize = initializeSort;
+sort.is = isSorted;
+const ARRAY_PEEK_PERCENTAGE$1 = 10;
+const ARRAY_THRESHOLD$1 = 100;
 const SORT_DIRECTION_ASCENDING = "ascending";
 const SORT_DIRECTION_DESCENDING = "descending";
 const modifiers = {

package/dist/internal/value/compare.mjs

@@ -39,26 +39,11 @@ compare.handlers = getCompareHandlers(compare, {
 });
 compare.register = registerComparator;
 compare.unregister = unregisterComparator;
-/**
-* Register a custom comparison handler for a class
-* @param constructor Class constructor
-* @param handler Method name or comparison function _(defaults to `compare`)_
-*/
-function registerComparator(constructor, handler) {
-	compare.handlers.register(constructor, handler);
-}
-/**
-* Unregister a custom comparison handler for a class
-* @param constructor Class constructor
-*/
-function unregisterComparator(constructor) {
-	compare.handlers.unregister(constructor);
-}
 function compareNumbers(first, second) {
-	const firstNumber = Number(first);
-	const secondNumber = Number(second);
-	if (Object.is(firstNumber, secondNumber)) return 0;
-	return firstNumber > secondNumber ? 1 : -1;
+	if (Object.is(first, second)) return 0;
+	if (Number.isNaN(first)) return -1;
+	if (Number.isNaN(second)) return 1;
+	return first > second ? 1 : -1;
 }
 function compareSymbols(first, second) {
 	return getString(first.description ?? first).localeCompare(getString(second.description ?? second));
@@ -73,9 +58,24 @@ function getComparisonParts(value) {
 	if (Array.isArray(value)) return value;
 	return typeof value === "object" ? [value] : words(getString(value));
 }
+/**
+* Register a custom comparison handler for a class
+* @param constructor Class constructor
+* @param handler Method name or comparison function _(defaults to `compare`)_
+*/
+function registerComparator(constructor, handler) {
+	compare.handlers.register(constructor, handler);
+}
+/**
+* Unregister a custom comparison handler for a class
+* @param constructor Class constructor
+*/
+function unregisterComparator(constructor) {
+	compare.handlers.unregister(constructor);
+}
 const comparators = {
 	bigint: compareNumbers,
-	boolean: compareNumbers,
+	boolean: (first, second) => compareNumbers(first ? 1 : 0, second ? 1 : 0),
 	number: compareNumbers,
 	symbol: compareSymbols
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.173.3",
+	"version": "0.175.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -230,7 +230,7 @@
 	},
 	"devDependencies": {
 		"@oxlint/plugins": "^1.59",
-		"@types/node": "^25.5",
+		"@types/node": "^25.6",
 		"@vitest/coverage-istanbul": "^4.1",
 		"eslint": "^10.2",
 		"jsdom": "^29.0",

package/src/array/sort.ts

@@ -104,7 +104,31 @@ type InternalSorterCompare = {
  */
 export type SortDirection = 'ascending' | 'descending';
 
-export type Sorter<Item> = (array: Item[]) => Item[];
+export type Sorter<Item> = {
+	/**
+	 * Sort an array of items
+	 * @param array Array to sort
+	 * @returns Sorted array
+	 */
+	(array: Item[]): Item[];
+
+	/**
+	 * Get the index for an item _(to be inserted into an array of items)_
+	 *
+	 * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+	 * @param array Array to get the index from
+	 * @param item Item to get the index for
+	 * @returns Index for item
+	 */
+	index(array: Item[], item: Item): number;
+
+	/**
+	 * Is the array sorted?
+	 * @param array Array to check
+	 * @returns `true` if sorted, otherwise `false`
+	 */
+	is(array: Item[]): boolean;
+};
 
 // #endregion
 
@@ -121,6 +145,82 @@ function getComparisonSorter(callback: Function, modifier: number): InternalSort
 	};
 }
 
+function getComparisonValue(
+	first: unknown,
+	second: unknown,
+	sorters: InternalSorter[],
+	length: number,
+): number {
+	for (let index = 0; index < length; index += 1) {
+		const sorter = sorters[index];
+
+		const values = [
+			sorter.get ? sorter.value!(first as PlainObject) : first,
+			sorter.get ? sorter.value!(second as PlainObject) : second,
+		];
+
+		const comparison =
+			(sorter.compare?.complex?.(first, values[0], second, values[1]) ??
+				sorter.compare?.simple?.(values[0], values[1]) ??
+				compare(values[0], values[1])) * sorter.modifier;
+
+		if (comparison !== 0) {
+			return comparison;
+		}
+	}
+
+	return 0;
+}
+
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on sorters _(and an optional default direction)_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @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
+ */
+function getIndex<Item>(
+	array: Item[],
+	item: Item,
+	sorters: Array<ArraySorter<Item>>,
+	descending?: boolean,
+): number;
+
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on a sorter _(and an optional default direction)_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @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
+ */
+function getIndex<Item>(
+	array: Item[],
+	item: Item,
+	sorter: ArraySorter<Item>,
+	descending?: boolean,
+): number;
+
+/**
+ * Get the index for an item _(to be inserted into an array of items)_ based on an optional default direction_
+ *
+ * _(If the array is not sorted, it will be treated as sorted, and the result may be inaccurate)_
+ * @param array Array to get the index from
+ * @param item Item to get the index for
+ * @param descending Sorted in descending order? _(defaults to `false`)_
+ * @returns Index for item
+ */
+function getIndex<Item>(array: Item[], item: Item, descending?: boolean): number;
+
+function getIndex(array: unknown[], item: unknown, first?: unknown, second?: unknown): number {
+	return getSortedIndex(array, item, getSorters(first, getModifier(first, second)));
+}
+
 function getModifier(first: unknown, second: unknown): number {
 	const direction =
 		first === true || second === true ? SORT_DIRECTION_DESCENDING : SORT_DIRECTION_ASCENDING;
@@ -152,6 +252,43 @@ function getObjectSorter(obj: PlainObject, modifier: number): InternalSorter | u
 	return sorter;
 }
 
+function getSortedIndex(array: unknown[], item: unknown, sorters: InternalSorter[]): number {
+	if (!Array.isArray(array)) {
+		return -1;
+	}
+
+	const {length} = array;
+
+	if (length === 0) {
+		return 0;
+	}
+
+	const sortersLength = sorters.length;
+
+	if (getComparisonValue(item, array[0], sorters, sortersLength) < 0) {
+		return 0;
+	}
+
+	if (getComparisonValue(item, array[length - 1], sorters, sortersLength) >= 0) {
+		return length;
+	}
+
+	let low = 0;
+	let high = length - 1;
+
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+
+		if (getComparisonValue(item, array[mid], sorters, sortersLength) < 0) {
+			high = mid - 1;
+		} else {
+			low = mid + 1;
+		}
+	}
+
+	return low;
+}
+
 function getSorter(value: unknown, modifier: number): InternalSorter | undefined {
 	switch (true) {
 		case typeof value === 'function':
@@ -184,6 +321,16 @@ function getSorters(value: unknown, modifier: number): InternalSorter[] {
 		}
 	}
 
+	if (sorters.length === 0) {
+		return [
+			{
+				modifier,
+				get: false,
+				identifier: 'default',
+			},
+		];
+	}
+
 	return sorters.filter(
 		(value, index, array) =>
 			array.findIndex(next => next.identifier === value.identifier) === index,
@@ -226,10 +373,98 @@ function initializeSort<Item>(sorter: ArraySorter<Item>, descending?: boolean):
 function initializeSort<Item>(descending?: boolean): Sorter<Item>;
 
 function initializeSort(first?: unknown, second?: unknown): Sorter<unknown> {
-	const modifier = getModifier(first, second);
-	const sorters = getSorters(first, modifier);
+	const sorters = getSorters(first, getModifier(first, second));
+
+	const sorter = (array: unknown[]) => sortArray(array, sorters);
 
-	return array => work(array, sorters, modifier);
+	sorter.index = (array: unknown[], item: unknown) => getSortedIndex(array, item, sorters);
+	sorter.is = (array: unknown[]) => isSortedArray(array, sorters);
+
+	return sorter as unknown as Sorter<unknown>;
+}
+
+/**
+ * Is the array sorted according to the sorters _(and the optional default direction)_?
+ * @param array Array to check
+ * @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`
+ */
+function isSorted<Item>(
+	array: Item[],
+	sorters: Array<ArraySorter<Item>>,
+	descending?: boolean,
+): boolean;
+
+/**
+ * Is the array sorted according to the sorter _(and the optional default direction)_?
+ * @param array Array to check
+ * @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`
+ */
+function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: boolean): boolean;
+
+/**
+ * Is the array sorted?
+ * @param array Array to check
+ * @param descending Sorted in descending order? _(defaults to `false`)_
+ * @returns `true` if sorted, otherwise `false`
+ */
+function isSorted<Item>(array: Item[], descending?: boolean): boolean;
+
+function isSorted(array: unknown[], first?: unknown, second?: unknown): boolean {
+	return isSortedArray(array, getSorters(first, getModifier(first, second)));
+}
+
+function isSortedArray(array: unknown[], sorters: InternalSorter[]): boolean {
+	if (!Array.isArray(array)) {
+		return false;
+	}
+
+	const {length} = array;
+
+	if (length < 2) {
+		return true;
+	}
+
+	const sortersLength = sorters.length;
+
+	let offset = 0;
+
+	if (length >= ARRAY_THRESHOLD) {
+		offset = Math.round(length / ARRAY_PEEK_PERCENTAGE);
+		offset = offset > ARRAY_THRESHOLD ? ARRAY_THRESHOLD : offset;
+
+		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]];
+
+			const [firstComparison, secondComparison] = [
+				getComparisonValue(firstItem, firstOffset, sorters, sortersLength),
+				getComparisonValue(secondItem, secondOffset, sorters, sortersLength),
+			];
+
+			if (firstComparison > 0 || secondComparison > 0) {
+				return false;
+			}
+		}
+	}
+
+	const end = length - offset - 1;
+
+	for (let index = offset; index < end; index += 1) {
+		const first = array[index];
+		const second = array[index + 1];
+
+		const comparison = getComparisonValue(first, second, sorters, sortersLength);
+
+		if (comparison > 0) {
+			return false;
+		}
+	}
+
+	return true;
 }
 
 /**
@@ -263,55 +498,35 @@ export function sort<Item>(array: Item[], sorter: ArraySorter<Item>, descending?
 export function sort<Item>(array: Item[], descending?: boolean): Item[];
 
 export function sort(array: unknown[], first?: unknown, second?: unknown): unknown[] {
-	const modifier = getModifier(first, second);
-
-	return work(array, getSorters(first, modifier), modifier);
+	return sortArray(array, getSorters(first, getModifier(first, second)));
 }
 
-function work(array: unknown[], sorters: InternalSorter[], modifier: number): unknown[] {
+function sortArray(array: unknown[], sorters: InternalSorter[]): unknown[] {
 	if (!Array.isArray(array)) {
 		return [];
 	}
 
-	if (array.length < 2) {
-		return array;
-	}
-
 	const {length} = sorters;
 
-	if (length === 0) {
-		return array.sort((first, second) => compare(first, second) * modifier);
-	}
-
-	return array.sort((first, second) => {
-		for (let index = 0; index < length; index += 1) {
-			const sorter = sorters[index];
-
-			const values = [
-				sorter.get ? sorter.value!(first as PlainObject) : first,
-				sorter.get ? sorter.value!(second as PlainObject) : second,
-			];
-
-			const comparison =
-				(sorter.compare?.complex?.(first, values[0], second, values[1]) ??
-					sorter.compare?.simple?.(values[0], values[1]) ??
-					compare(values[0], values[1])) * sorter.modifier;
-
-			if (comparison !== 0) {
-				return comparison;
-			}
-		}
-
-		return 0;
-	});
+	return array.length > 1
+		? array.sort((first, second) => getComparisonValue(first, second, sorters, length))
+		: array;
 }
 
+sort.index = getIndex;
+
 sort.initialize = initializeSort;
 
+sort.is = isSorted;
+
 // #endregion
 
 // #region Variables
 
+const ARRAY_PEEK_PERCENTAGE = 10;
+
+const ARRAY_THRESHOLD = 100;
+
 export const SORT_DIRECTION_ASCENDING: SortDirection = 'ascending';
 
 export const SORT_DIRECTION_DESCENDING: SortDirection = 'descending';

package/src/internal/value/compare.ts

@@ -80,38 +80,20 @@ compare.register = registerComparator;
 
 compare.unregister = unregisterComparator;
 
-/**
- * Register a custom comparison handler for a class
- * @param constructor Class constructor
- * @param handler Method name or comparison function _(defaults to `compare`)_
- */
-function registerComparator<Instance>(
-	constructor: Constructor<Instance>,
-	handler?: string | ((first: Instance, second: Instance) => number),
-): void {
-	compare.handlers.register(constructor, handler);
-}
-
-/**
- * Unregister a custom comparison handler for a class
- * @param constructor Class constructor
- */
-function unregisterComparator<Instance>(constructor: Constructor<Instance>): void {
-	compare.handlers.unregister(constructor);
-}
+function compareNumbers(first: bigint | number, second: bigint | number): number {
+	if (Object.is(first, second)) {
+		return 0;
+	}
 
-function compareNumbers(
-	first: bigint | boolean | number,
-	second: bigint | boolean | number,
-): number {
-	const firstNumber = Number(first);
-	const secondNumber = Number(second);
+	if (Number.isNaN(first)) {
+		return -1;
+	}
 
-	if (Object.is(firstNumber, secondNumber)) {
-		return 0;
+	if (Number.isNaN(second)) {
+		return 1;
 	}
 
-	return firstNumber > secondNumber ? 1 : -1;
+	return first > second ? 1 : -1;
 }
 
 function compareSymbols(first: symbol, second: symbol): number {
@@ -147,13 +129,33 @@ function getComparisonParts(value: unknown): unknown[] {
 	return typeof value === 'object' ? [value] : words(getString(value));
 }
 
+/**
+ * Register a custom comparison handler for a class
+ * @param constructor Class constructor
+ * @param handler Method name or comparison function _(defaults to `compare`)_
+ */
+function registerComparator<Instance>(
+	constructor: Constructor<Instance>,
+	handler?: string | ((first: Instance, second: Instance) => number),
+): void {
+	compare.handlers.register(constructor, handler);
+}
+
+/**
+ * Unregister a custom comparison handler for a class
+ * @param constructor Class constructor
+ */
+function unregisterComparator<Instance>(constructor: Constructor<Instance>): void {
+	compare.handlers.unregister(constructor);
+}
+
 // #endregion
 
 // #region Variables
 
 const comparators: Record<string, Comparator> = {
 	bigint: compareNumbers,
-	boolean: compareNumbers,
+	boolean: (first, second) => compareNumbers(first ? 1 : 0, second ? 1 : 0),
 	number: compareNumbers,
 	symbol: compareSymbols,
 };