@oscarpalmer/atoms 0.174.0 → 0.176.0

package/dist/array/sort.d.mts

@@ -72,6 +72,15 @@ type Sorter<Item> = {
    * @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
@@ -79,6 +88,38 @@ type Sorter<Item> = {
    */
   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
@@ -102,7 +143,7 @@ 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 use
+ * @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`
  */
@@ -110,7 +151,7 @@ declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>
 /**
  * Is the array sorted according to the sorter _(and the optional default direction)_?
  * @param array Array to check
- * @param sorter Sorter to use
+ * @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`
  */
@@ -118,7 +159,7 @@ declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descen
 /**
  * Is the array sorted?
  * @param array Array to check
- * @param descending Sorted in descending order? _(defaults to `false)_
+ * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns `true` if sorted, otherwise `false`
  */
 declare function isSorted<Item>(array: Item[], descending?: boolean): boolean;
@@ -146,6 +187,7 @@ 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;
 }

package/dist/array/sort.mjs

@@ -18,6 +18,9 @@ function getComparisonValue(first, second, sorters, length) {
 	}
 	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];
 }
@@ -31,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);
@@ -66,6 +85,7 @@ function getValueSorter(value, modifier) {
 function initializeSort(first, second) {
 	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;
 }
@@ -104,6 +124,7 @@ function sortArray(array, sorters) {
 	const { length } = sorters;
 	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;

package/dist/index.d.mts

@@ -1173,6 +1173,15 @@ type Sorter<Item> = {
    * @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
@@ -1180,6 +1189,38 @@ type Sorter<Item> = {
    */
   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
@@ -1203,7 +1244,7 @@ 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 use
+ * @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`
  */
@@ -1211,7 +1252,7 @@ declare function isSorted<Item>(array: Item[], sorters: Array<ArraySorter<Item>>
 /**
  * Is the array sorted according to the sorter _(and the optional default direction)_?
  * @param array Array to check
- * @param sorter Sorter to use
+ * @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`
  */
@@ -1219,7 +1260,7 @@ declare function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descen
 /**
  * Is the array sorted?
  * @param array Array to check
- * @param descending Sorted in descending order? _(defaults to `false)_
+ * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns `true` if sorted, otherwise `false`
  */
 declare function isSorted<Item>(array: Item[], descending?: boolean): boolean;
@@ -1247,6 +1288,7 @@ 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;
 }
@@ -2510,6 +2552,30 @@ declare function registerCloner<Instance>(constructor: Constructor<Instance>, ha
  */
 declare function unregisterCloner<Instance>(constructor: Constructor<Instance>): void;
 //#endregion
+//#region src/value/collection.d.ts
+/**
+ * Does the value exist for a key in a map?
+ * @param map Map to check in
+ * @param value Value to check for
+ * @returns `true` if the value exists, otherwise `false`
+ */
+declare function inMap<Value>(map: Map<unknown, Value>, value: Value): boolean;
+/**
+ * Does the value exist for a key in a map?
+ * @param map Map to check in
+ * @param value Value to check for
+ * @param key To return the key for the value
+ * @return The key for the value if it exists, otherwise `undefined`
+ */
+declare function inMap<Key, Value>(map: Map<Key, Value>, value: Value, key: true): Key;
+/**
+ * Does the value exist in a set?
+ * @param set Set to check in
+ * @param value Value to check for
+ * @returns `true` if the value exists, otherwise `false`
+ */
+declare function inSet<Value>(set: Set<Value>, value: Value): boolean;
+//#endregion
 //#region src/value/diff.d.ts
 /**
  * Options for value comparison
@@ -4441,4 +4507,4 @@ declare class SizedSet<Value = unknown> extends Set<Value> {
   get(value: Value, update?: boolean): Value | undefined;
 }
 //#endregion
-export { AnyResult, ArrayComparisonSorter, ArrayKeySorter, ArrayOrPlainObject, ArrayPosition, ArrayValueSorter, Asserter, AsyncCancelableCallback, AttemptFlow, AttemptFlowPromise, type Beacon, type BeaconOptions, BuiltIns, CancelableCallback, CancelablePromise, type Color, Constructor, DiffOptions, DiffResult, DiffValue, EqualOptions, Err, EventPosition, ExtendedErr, ExtendedResult, Flow, FlowPromise, FulfilledPromise, GenericAsyncCallback, GenericCallback, type HSLAColor, type HSLColor, HasValue, Key, KeyedValue, type Logger, type Memoized, type MemoizedOptions, MergeOptions, Merger, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, type Observable, type Observer, Ok, OnceAsyncCallback, OnceCallback, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PlainObject, Primitive, PromiseData, PromiseHandlers, PromiseOptions, PromiseParameters, PromiseStrategy, PromiseTimeoutError, PromisesItems, PromisesOptions, PromisesResult, PromisesUnwrapped, PromisesValue, PromisesValues, type Queue, QueueError, type QueueOptions, type Queued, type QueuedResult, type RGBAColor, type RGBColor, RejectedPromise, RequiredKeys, Result, ResultMatch, RetryError, RetryOptions, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, Simplify, SizedMap, SizedSet, Smushed, SortDirection, Sorter, type Subscription, TemplateOptions, type Time, ToString, TypedArray, Unsmushed, UnwrapValue, assert, attempt, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getTimedPromise, getUuid, getValue, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { AnyResult, ArrayComparisonSorter, ArrayKeySorter, ArrayOrPlainObject, ArrayPosition, ArrayValueSorter, Asserter, AsyncCancelableCallback, AttemptFlow, AttemptFlowPromise, type Beacon, type BeaconOptions, BuiltIns, CancelableCallback, CancelablePromise, type Color, Constructor, DiffOptions, DiffResult, DiffValue, EqualOptions, Err, EventPosition, ExtendedErr, ExtendedResult, Flow, FlowPromise, FulfilledPromise, GenericAsyncCallback, GenericCallback, type HSLAColor, type HSLColor, HasValue, Key, KeyedValue, type Logger, type Memoized, type MemoizedOptions, MergeOptions, Merger, NestedArray, NestedKeys, NestedPartial, NestedValue, NestedValues, NumericalKeys, NumericalValues, type Observable, type Observer, Ok, OnceAsyncCallback, OnceCallback, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PlainObject, Primitive, PromiseData, PromiseHandlers, PromiseOptions, PromiseParameters, PromiseStrategy, PromiseTimeoutError, PromisesItems, PromisesOptions, PromisesResult, PromisesUnwrapped, PromisesValue, PromisesValues, type Queue, QueueError, type QueueOptions, type Queued, type QueuedResult, type RGBAColor, type RGBColor, RejectedPromise, RequiredKeys, Result, ResultMatch, RetryError, RetryOptions, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, Simplify, SizedMap, SizedSet, Smushed, SortDirection, Sorter, type Subscription, TemplateOptions, type Time, ToString, TypedArray, Unsmushed, UnwrapValue, assert, attempt, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getTimedPromise, getUuid, getValue, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/index.mjs

@@ -928,6 +928,9 @@ function getComparisonValue(first, second, sorters, length) {
 	}
 	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];
 }
@@ -941,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);
@@ -976,6 +995,7 @@ function getValueSorter(value, modifier) {
 function initializeSort(first, second) {
 	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;
 }
@@ -1014,6 +1034,7 @@ function sortArray(array, sorters) {
 	const { length } = sorters;
 	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;
@@ -2443,6 +2464,26 @@ function tryStructuredClone(value, depth, references) {
 }
 const MAX_CLONE_DEPTH = 100;
 //#endregion
+//#region src/value/collection.ts
+function inMap(map, value, key) {
+	const getKey = key === true;
+	if (!(map instanceof Map)) return getKey ? void 0 : false;
+	if (!getKey) return inSet(new Set(map.values()), value);
+	for (const [key, item] of map) if (equal(item, value)) return key;
+}
+/**
+* Does the value exist in a set?
+* @param set Set to check in
+* @param value Value to check for
+* @returns `true` if the value exists, otherwise `false`
+*/
+function inSet(set, value) {
+	if (!(set instanceof Set)) return false;
+	if (set.has(value)) return true;
+	for (const item of set) if (equal(item, value)) return true;
+	return false;
+}
+//#endregion
 //#region src/value/diff.ts
 /**
 * Find the differences between two values
@@ -4567,4 +4608,4 @@ var SizedSet = class extends Set {
 	}
 };
 //#endregion
-export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError, QueueError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, assert, attempt, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getTimedPromise, getUuid, getValue, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };
+export { CancelablePromise, PROMISE_ABORT_EVENT, PROMISE_ABORT_OPTIONS, PROMISE_ERROR_NAME, PROMISE_MESSAGE_EXPECTATION_ATTEMPT, PROMISE_MESSAGE_EXPECTATION_RESULT, PROMISE_MESSAGE_EXPECTATION_TIMED, PROMISE_MESSAGE_TIMEOUT, PROMISE_STRATEGY_ALL, PROMISE_STRATEGY_DEFAULT, PROMISE_TYPE_FULFILLED, PROMISE_TYPE_REJECTED, PromiseTimeoutError, QueueError, RetryError, SORT_DIRECTION_ASCENDING, SORT_DIRECTION_DESCENDING, SizedMap, SizedSet, assert, attempt, attemptFlow, attemptPipe, attemptPromise, average, beacon, between, camelCase, cancelable, capitalize, ceil, chunk, clamp, clone, compact, compare, count, debounce, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, getArray, getArrayPosition, getColor, getError, getForegroundColor, getHexColor, getHexaColor, getHslColor, getHslaColor, getNormalizedHex, getNumber, getRandomBoolean, getRandomCharacters, getRandomColor, getRandomFloat, getRandomHex, getRandomInteger, getRandomItem, getRandomItems, getRgbColor, getRgbaColor, getString, getTimedPromise, getUuid, getValue, groupBy, handleResult, hasValue, hexToHsl, hexToHsla, hexToRgb, hexToRgba, hslToHex, hslToRgb, hslToRgba, ignoreKey, inMap, inSet, includes, includesArray, indexOf, indexOfArray, insert, intersection, isArrayOrPlainObject, isColor, isConstructor, isEmpty, isError, isFulfilled, isHexColor, isHslColor, isHslLike, isHslaColor, isInstanceOf, isKey, isNonNullable, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, slice, smush, snakeCase, sort, splice, startsWith, startsWithArray, sum, swap, take, template, throttle, timed, times, titleCase, toMap, toQuery, toRecord, toResult, toSet, toggle, trim, truncate, tryDecode, tryEncode, union, unique, unsmush, unwrap, update, upperCase, words };

package/dist/value/collection.d.mts

@@ -0,0 +1,25 @@
+//#region src/value/collection.d.ts
+/**
+ * Does the value exist for a key in a map?
+ * @param map Map to check in
+ * @param value Value to check for
+ * @returns `true` if the value exists, otherwise `false`
+ */
+declare function inMap<Value>(map: Map<unknown, Value>, value: Value): boolean;
+/**
+ * Does the value exist for a key in a map?
+ * @param map Map to check in
+ * @param value Value to check for
+ * @param key To return the key for the value
+ * @return The key for the value if it exists, otherwise `undefined`
+ */
+declare function inMap<Key, Value>(map: Map<Key, Value>, value: Value, key: true): Key;
+/**
+ * Does the value exist in a set?
+ * @param set Set to check in
+ * @param value Value to check for
+ * @returns `true` if the value exists, otherwise `false`
+ */
+declare function inSet<Value>(set: Set<Value>, value: Value): boolean;
+//#endregion
+export { inMap, inSet };

package/dist/value/collection.mjs

@@ -0,0 +1,22 @@
+import { equal } from "../internal/value/equal.mjs";
+//#region src/value/collection.ts
+function inMap(map, value, key) {
+	const getKey = key === true;
+	if (!(map instanceof Map)) return getKey ? void 0 : false;
+	if (!getKey) return inSet(new Set(map.values()), value);
+	for (const [key, item] of map) if (equal(item, value)) return key;
+}
+/**
+* Does the value exist in a set?
+* @param set Set to check in
+* @param value Value to check for
+* @returns `true` if the value exists, otherwise `false`
+*/
+function inSet(set, value) {
+	if (!(set instanceof Set)) return false;
+	if (set.has(value)) return true;
+	for (const item of set) if (equal(item, value)) return true;
+	return false;
+}
+//#endregion
+export { inMap, inSet };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.174.0",
+	"version": "0.176.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -200,6 +200,10 @@
 			"types": "./dist/value/clone.d.mts",
 			"default": "./dist/value/clone.mjs"
 		},
+		"./value/collection": {
+			"types": "./dist/value/collection.d.mts",
+			"default": "./dist/value/collection.mjs"
+		},
 		"./value/compare": {
 			"types": "./dist/internal/value/compare.d.mts",
 			"default": "./dist/internal/value/compare.mjs"

package/src/array/sort.ts

@@ -112,6 +112,16 @@ export type Sorter<Item> = {
 	 */
 	(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
@@ -162,6 +172,55 @@ function getComparisonValue(
 	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;
@@ -193,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':
@@ -281,6 +377,7 @@ function initializeSort(first?: unknown, second?: unknown): Sorter<unknown> {
 
 	const sorter = (array: unknown[]) => sortArray(array, sorters);
 
+	sorter.index = (array: unknown[], item: unknown) => getSortedIndex(array, item, sorters);
 	sorter.is = (array: unknown[]) => isSortedArray(array, sorters);
 
 	return sorter as unknown as Sorter<unknown>;
@@ -289,7 +386,7 @@ function initializeSort(first?: unknown, second?: unknown): Sorter<unknown> {
 /**
  * Is the array sorted according to the sorters _(and the optional default direction)_?
  * @param array Array to check
- * @param sorters Sorters to use
+ * @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`
  */
@@ -302,7 +399,7 @@ function isSorted<Item>(
 /**
  * Is the array sorted according to the sorter _(and the optional default direction)_?
  * @param array Array to check
- * @param sorter Sorter to use
+ * @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`
  */
@@ -311,7 +408,7 @@ function isSorted<Item>(array: Item[], sorter: ArraySorter<Item>, descending?: b
 /**
  * Is the array sorted?
  * @param array Array to check
- * @param descending Sorted in descending order? _(defaults to `false)_
+ * @param descending Sorted in descending order? _(defaults to `false`)_
  * @returns `true` if sorted, otherwise `false`
  */
 function isSorted<Item>(array: Item[], descending?: boolean): boolean;
@@ -416,6 +513,8 @@ function sortArray(array: unknown[], sorters: InternalSorter[]): unknown[] {
 		: array;
 }
 
+sort.index = getIndex;
+
 sort.initialize = initializeSort;
 
 sort.is = isSorted;

package/src/index.ts

@@ -29,6 +29,7 @@ export * from './string/match';
 export * from './string/template';
 
 export * from './value/clone';
+export * from './value/collection';
 export * from './value/diff';
 export * from './value/index';
 export * from './value/merge';

package/src/value/collection.ts

@@ -0,0 +1,60 @@
+import {equal} from '../internal/value/equal';
+
+/**
+ * Does the value exist for a key in a map?
+ * @param map Map to check in
+ * @param value Value to check for
+ * @returns `true` if the value exists, otherwise `false`
+ */
+export function inMap<Value>(map: Map<unknown, Value>, value: Value): boolean;
+
+/**
+ * Does the value exist for a key in a map?
+ * @param map Map to check in
+ * @param value Value to check for
+ * @param key To return the key for the value
+ * @return The key for the value if it exists, otherwise `undefined`
+ */
+export function inMap<Key, Value>(map: Map<Key, Value>, value: Value, key: true): Key;
+
+export function inMap<Key, Value>(map: Map<Key, Value>, value: Value, key?: unknown): unknown {
+	const getKey = key === true;
+
+	if (!(map instanceof Map)) {
+		return getKey ? undefined : false;
+	}
+
+	if (!getKey) {
+		return inSet(new Set(map.values()), value);
+	}
+
+	for (const [key, item] of map) {
+		if (equal(item, value)) {
+			return key;
+		}
+	}
+}
+
+/**
+ * Does the value exist in a set?
+ * @param set Set to check in
+ * @param value Value to check for
+ * @returns `true` if the value exists, otherwise `false`
+ */
+export function inSet<Value>(set: Set<Value>, value: Value): boolean {
+	if (!(set instanceof Set)) {
+		return false;
+	}
+
+	if (set.has(value)) {
+		return true;
+	}
+
+	for (const item of set) {
+		if (equal(item, value)) {
+			return true;
+		}
+	}
+
+	return false;
+}