@oscarpalmer/atoms 0.178.0 → 0.179.1

package/dist/index.d.mts

@@ -2669,6 +2669,113 @@ declare function titleCase(value: string): string;
  */
 declare function upperCase(value: string): string;
 //#endregion
+//#region src/string/fuzzy.d.ts
+/**
+ * Fuzzy searcher for an array of items
+ */
+declare class Fuzzy<Item> {
+  #private;
+  /**
+   * Get items currently being searched through
+   */
+  get items(): Item[];
+  /**
+   * Set new items to search through
+   */
+  set items(items: Item[]);
+  /**
+   * Get strings currently being searched through _(the stringified version of `items`)_
+   */
+  get strings(): string[];
+  constructor(state: FuzzyState<Item>);
+  /**
+   * Search for items matching the given value
+   * @param value Value to search for
+   * @param options Search options
+   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   */
+  search(value: string, options?: FuzzyOptions): FuzzyResult<Item>;
+  /**
+   * Search for items matching the given value
+   * @param value Value to search for
+   * @param limit Maximum number of combined items to return in `exact` and `similar`
+   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   */
+  search(value: string, limit: number): FuzzyResult<Item>;
+}
+type FuzzyConfiguration<Item> = {
+  /**
+   * Handler to stringify items
+   *
+   * May be a function that takes an item and returns a string, or if items are plain objects, a key of the item to use to grab a string value from
+   *
+   * Defaults to `getString`
+   */
+  handler?: (item: Item) => string;
+} & (Item extends PlainObject ? {
+  /**
+   * Key to use to stringify items
+   *
+   * Prioritized over `handler`
+   */
+  key?: keyof Item;
+} : {}) & FuzzyOptions;
+type FuzzyOptions = {
+  /**
+   * Maximum number of combined items to return in `exact` and `similar` _(defaults to all matches)_
+   */
+  limit?: number;
+  /**
+   * Maximum score difference between the best and worst similar matches included in results; higher values cast a wider net _(defaults to 5)_
+   */
+  tolerance?: number;
+};
+/**
+ * Search results from a fuzzy search, with exact and similar matches
+ */
+type FuzzyResult<Item> = {
+  /**
+   * Ordered items that exactly match the search value
+   */
+  exact: Item[];
+  /**
+   * Ordered items that are similar to the search value, ranked by relevance
+   */
+  similar: Item[];
+};
+/**
+ * Options for fuzzy searching
+ */
+type FuzzySearchOptions = FuzzyOptions;
+type FuzzyState<Item> = {
+  handler: (item: Item) => string;
+  items: Item[];
+  limit?: number;
+  strings: string[];
+  tolerance: number;
+};
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param key Key to use to stringify items
+ * @returns Fuzzy searcher
+ */
+declare function fuzzy<Item extends PlainObject, ItemKey extends keyof Item>(items: Item[], key?: ItemKey): Fuzzy<Item>;
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param handler Handler to stringify items
+ * @returns Fuzzy searcher
+ */
+declare function fuzzy<Item>(items: Item[], handler?: (item: Item) => string): Fuzzy<Item>;
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param configuration Fuzzy configuration
+ * @returns Fuzzy searcher
+ */
+declare function fuzzy<Item>(items: Item[], configuration?: FuzzyConfiguration<Item>): Fuzzy<Item>;
+//#endregion
 //#region src/string/index.d.ts
 declare function dedent(strings: TemplateStringsArray, ...values: unknown[]): string;
 declare function dedent(value: string): string;
@@ -4826,4 +4933,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, dedent, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, first, 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, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, last, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, single, 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, FuzzyConfiguration, FuzzyOptions, FuzzyResult, FuzzySearchOptions, 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, dedent, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, first, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, fuzzy, 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, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, last, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, single, 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

@@ -175,7 +175,7 @@ function compact(array, strict) {
 //#endregion
 //#region src/internal/array/index-of.ts
 function indexOf(array, ...parameters) {
-	return findValue(FIND_VALUE_INDEX, array, parameters);
+	return findValue(FIND_VALUE_INDEX, array, parameters, false);
 }
 //#endregion
 //#region src/internal/is.ts
@@ -2316,6 +2316,314 @@ const delimiters = {
 let memoizedCapitalize;
 let memoizedTitleCase;
 //#endregion
+//#region src/is.ts
+/**
+* Is the value empty, or only containing `null` or `undefined` values?
+* @param value Value to check
+* @returns `true` if the value is considered empty, otherwise `false`
+*/
+function isEmpty(value) {
+	if (value == null) return true;
+	if (typeof value === "string") return value.length === 0;
+	const values = getArray(value);
+	const { length } = values;
+	for (let index = 0; index < length; index += 1) if (values[index] != null) return false;
+	return true;
+}
+/**
+* Is the value not empty, or holding non-empty values?
+* @param value Value to check
+* @returns `true` if the value is not considered empty, otherwise `false`
+*/
+function isNonEmpty(value) {
+	return !isEmpty(value);
+}
+/**
+* Is the value not `undefined` or `null`?
+* @param value Value to check
+* @returns `true` if the value is not `undefined` or `null`, otherwise `false`
+*/
+function isNonNullable(value) {
+	return value != null;
+}
+/**
+* Is the value not `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
+* @param value Value to check
+* @returns `true` if the value is not `undefined`, `null`, or matches an empty string, otherwise `false`
+*/
+function isNonNullableOrEmpty(value) {
+	return value != null && getString(value) !== "";
+}
+/**
+* Is the value not `undefined`, `null`, or stringified as a whitespace-only string?
+* @param value Value to check
+* @returns `true` if the value is not `undefined`, `null`, or matches a whitespace-only string, otherwise `false`
+*/
+function isNonNullableOrWhitespace(value) {
+	return value != null && !EXPRESSION_WHITESPACE.test(getString(value));
+}
+/**
+* Is the value not a number or a number-like string?
+* @param value Value to check
+* @returns `true` if the value is not a number or a number-like string, otherwise `false`
+*/
+function isNonNumerical(value) {
+	return !isNumerical(value);
+}
+/**
+* Is the value not an object _(or function)_?
+* @param value Value to check
+* @returns `true` if the value is not an object, otherwise `false`
+*/
+function isNonObject(value) {
+	return !isObject(value);
+}
+/**
+* Is the value `undefined` or `null`?
+* @param value Value to check
+* @returns `true` if the value is `undefined` or `null`, otherwise `false`
+*/
+function isNullable(value) {
+	return value == null;
+}
+/**
+* Is the value `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
+* @param value Value to check
+* @returns `true` if the value is nullable or matches an empty string, otherwise `false`
+*/
+function isNullableOrEmpty(value) {
+	return value == null || getString(value) === "";
+}
+/**
+* Is the value `undefined`, `null`, or stringified as a whitespace-only string?
+* @param value Value to check
+* @returns `true` if the value is nullable or matches a whitespace-only string, otherwise `false`
+*/
+function isNullableOrWhitespace(value) {
+	return value == null || EXPRESSION_WHITESPACE.test(getString(value));
+}
+/**
+* Is the value a number or a number-like string?
+* @param value Value to check
+* @returns `true` if the value is a number or a number-like string, otherwise `false`
+*/
+function isNumerical(value) {
+	return isNumber(value) || typeof value === "string" && value.trim().length > 0 && !Number.isNaN(+value);
+}
+/**
+* Is the value an object _(or function)_?
+* @param value Value to check
+* @returns `true` if the value matches, otherwise `false`
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null || typeof value === "function";
+}
+const EXPRESSION_WHITESPACE = /^\s*$/;
+//#endregion
+//#region src/string/match.ts
+/**
+* Check if a string ends with a specified substring
+* @param haystack String to look in
+* @param needle String to look for
+* @param ignoreCase Ignore case when matching? _(defaults to `false`)_
+* @returns `true` if the string ends with the given substring, otherwise `false`
+*/
+function endsWith(haystack, needle, ignoreCase) {
+	return match(MATCH_ENDS_WITH, haystack, needle, ignoreCase === true);
+}
+/**
+* Check if a string includes a specified substring
+* @param haystack String to look in
+* @param needle String to look for
+* @param ignoreCase Ignore case when matching? _(defaults to `false`)_
+* @returns `true` if the string includes the given substring, otherwise `false`
+*/
+function includes(haystack, needle, ignoreCase) {
+	return match(MATCH_INCLUDES, haystack, needle, ignoreCase === true);
+}
+function match(type, haystack, needle, ignoreCase) {
+	if (typeof haystack !== "string" || typeof needle !== "string") return false;
+	matchMemoizers[type] ??= memoize(matchCallback.bind(type));
+	return matchMemoizers[type].run(haystack, needle, ignoreCase);
+}
+function matchCallback(haystack, needle, ignoreCase) {
+	return (ignoreCase ? haystack.toLocaleLowerCase() : haystack)[this](ignoreCase ? needle.toLocaleLowerCase() : needle);
+}
+/**
+* Check if a string starts with a specified substring
+* @param haystack String to look in
+* @param needle String to look for
+* @param ignoreCase Ignore case when matching? _(defaults to `false`)_
+* @returns `true` if the string starts with the given substring, otherwise `false`
+*/
+function startsWith(haystack, needle, ignoreCase) {
+	return match(MATCH_STARTS_WITH, haystack, needle, ignoreCase === true);
+}
+const MATCH_ENDS_WITH = "endsWith";
+const MATCH_INCLUDES = "includes";
+const MATCH_STARTS_WITH = "startsWith";
+const matchMemoizers = {};
+//#endregion
+//#region src/string/fuzzy.ts
+/**
+* Fuzzy searcher for an array of items
+*/
+var Fuzzy = class {
+	#state;
+	/**
+	* Get items currently being searched through
+	*/
+	get items() {
+		return this.#state.items.slice();
+	}
+	/**
+	* Set new items to search through
+	*/
+	set items(items) {
+		if (Array.isArray(items)) {
+			this.#state.items = items.slice();
+			this.#state.strings = items.map(this.#state.handler);
+		}
+	}
+	/**
+	* Get strings currently being searched through _(the stringified version of `items`)_
+	*/
+	get strings() {
+		return this.#state.strings.slice();
+	}
+	constructor(state) {
+		this.#state = state;
+	}
+	search(value, options) {
+		return search(this.#state.items, this.#state.strings, value, options == null ? this.#state : getOptions$1(options, this.#state));
+	}
+};
+function getHandler(input) {
+	if (input == null || input === getString) return getString;
+	switch (typeof input) {
+		case "function": return input;
+		case "string": return (item) => item[input];
+		default:
+			if (isPlainObject(input)) return getHandler(input.key ?? input.handler);
+			throw new TypeError(MESSAGE_HANDLER);
+	}
+}
+function getItems(items) {
+	return items.sort((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
+}
+function getOptions$1(input, state) {
+	const options = isPlainObject(input) ? input : {};
+	const limit = typeof input === "number" ? input : options.limit;
+	if (typeof limit === "number" && !Number.isNaN(limit) && limit >= 1) options.limit = Math.floor(limit);
+	else options.limit = state?.limit;
+	if (typeof options.tolerance === "number" && !Number.isNaN(options.tolerance)) options.tolerance = options.tolerance < 0 ? 0 : Math.floor(options.tolerance);
+	else options.tolerance = state?.tolerance ?? PROXIMITY_THRESHOLD;
+	return options;
+}
+function getState$1(items, input) {
+	const handler = getHandler(input);
+	const options = getOptions$1(input);
+	return {
+		handler,
+		items: items.slice(),
+		limit: options.limit,
+		strings: items.map(handler),
+		tolerance: options.tolerance
+	};
+}
+function fuzzy(items, configuration) {
+	if (!Array.isArray(items)) throw new TypeError(MESSAGE_ARRAY);
+	return new Fuzzy(getState$1(items, configuration));
+}
+function isSubsequence(haystack, needle) {
+	const lowerCaseHaystack = lowerCase(haystack);
+	const lowerCaseNeedle = lowerCase(needle);
+	const haystackLength = lowerCaseHaystack.length;
+	const needleLength = lowerCaseNeedle.length;
+	let needleIndex = 0;
+	for (let haystackIndex = 0; haystackIndex < haystackLength; haystackIndex += 1) {
+		if (lowerCaseHaystack[haystackIndex] === lowerCaseNeedle[needleIndex]) needleIndex += 1;
+		if (needleIndex === needleLength) return true;
+	}
+	return false;
+}
+function getScore(haystack, needle) {
+	if (!isSubsequence(haystack, needle)) return -1;
+	const lowerCaseHaystack = lowerCase(haystack);
+	const lowerCaseNeedle = lowerCase(needle);
+	const needleLength = lowerCaseNeedle.length;
+	let needleIndex = 0;
+	let previousMatchIndex = -1;
+	let score = 0;
+	for (let haystackIndex = 0; haystackIndex < lowerCaseHaystack.length; haystackIndex += 1) {
+		if (lowerCaseHaystack[haystackIndex] === lowerCaseNeedle[needleIndex]) {
+			score += 1;
+			if (haystackIndex === 0) score += 1;
+			if (previousMatchIndex !== -1) {
+				const gap = haystackIndex - previousMatchIndex - 1;
+				score += Math.max(0, PROXIMITY_THRESHOLD - gap);
+			}
+			previousMatchIndex = haystackIndex;
+			needleIndex += 1;
+		}
+		if (needleIndex === needleLength) break;
+	}
+	score -= Math.floor(lowerCaseHaystack.length / LENGTH_DIVISOR);
+	return Math.max(0, score);
+}
+function search(items, strings, input, options) {
+	const result = {
+		exact: [],
+		similar: []
+	};
+	const value = typeof input === "string" ? input.trim() : "";
+	if (value.length === 0) {
+		result.exact = items.slice(0, options.limit);
+		return result;
+	}
+	let { length } = items;
+	const exact = [];
+	const similar = [];
+	const scored = {};
+	for (let index = 0; index < length; index += 1) {
+		const item = items[index];
+		const haystack = strings[index];
+		if (includes(haystack, value, true)) {
+			exact.push({
+				item,
+				haystack
+			});
+			continue;
+		}
+		const score = getScore(haystack, value);
+		if (score > -1) {
+			scored[score] ??= [];
+			scored[score].push({
+				item,
+				haystack
+			});
+		}
+	}
+	const keys = Object.keys(scored).map(Number).sort((first, second) => second - first);
+	length = keys.length;
+	if (length > 0 && options.tolerance > 0) {
+		const maxScore = keys[0];
+		for (let index = 0; index < length; index += 1) {
+			const key = keys[index];
+			if (maxScore - key > options.tolerance) break;
+			similar.push(...getItems(scored[key]));
+		}
+	}
+	result.exact = getItems(options.limit == null ? exact : exact.slice(0, options.limit));
+	if (options.limit == null) result.similar = similar;
+	else result.similar = similar.slice(0, options.limit - result.exact.length);
+	return result;
+}
+const LENGTH_DIVISOR = 3;
+const MESSAGE_ARRAY = "Fuzzy requires an array of items";
+const MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
+const PROXIMITY_THRESHOLD = 5;
+//#endregion
 //#region src/string/index.ts
 function dedent(value, ...values) {
 	let actual;
@@ -2404,50 +2712,6 @@ function truncate(value, length, suffix) {
 }
 const ZERO = "0";
 //#endregion
-//#region src/string/match.ts
-/**
-* Check if a string ends with a specified substring
-* @param haystack String to look in
-* @param needle String to look for
-* @param ignoreCase Ignore case when matching? _(defaults to `false`)_
-* @returns `true` if the string ends with the given substring, otherwise `false`
-*/
-function endsWith(haystack, needle, ignoreCase) {
-	return match(MATCH_ENDS_WITH, haystack, needle, ignoreCase === true);
-}
-/**
-* Check if a string includes a specified substring
-* @param haystack String to look in
-* @param needle String to look for
-* @param ignoreCase Ignore case when matching? _(defaults to `false`)_
-* @returns `true` if the string includes the given substring, otherwise `false`
-*/
-function includes(haystack, needle, ignoreCase) {
-	return match(MATCH_INCLUDES, haystack, needle, ignoreCase === true);
-}
-function match(type, haystack, needle, ignoreCase) {
-	if (typeof haystack !== "string" || typeof needle !== "string") return false;
-	matchMemoizers[type] ??= memoize(matchCallback.bind(type));
-	return matchMemoizers[type].run(haystack, needle, ignoreCase);
-}
-function matchCallback(haystack, needle, ignoreCase) {
-	return (ignoreCase ? haystack.toLocaleLowerCase() : haystack)[this](ignoreCase ? needle.toLocaleLowerCase() : needle);
-}
-/**
-* Check if a string starts with a specified substring
-* @param haystack String to look in
-* @param needle String to look for
-* @param ignoreCase Ignore case when matching? _(defaults to `false`)_
-* @returns `true` if the string starts with the given substring, otherwise `false`
-*/
-function startsWith(haystack, needle, ignoreCase) {
-	return match(MATCH_STARTS_WITH, haystack, needle, ignoreCase === true);
-}
-const MATCH_ENDS_WITH = "endsWith";
-const MATCH_INCLUDES = "includes";
-const MATCH_STARTS_WITH = "startsWith";
-const matchMemoizers = {};
-//#endregion
 //#region src/string/template.ts
 function getTemplateOptions(input) {
 	const options = isPlainObject(input) ? input : {};
@@ -3737,110 +4001,6 @@ function getColor(value) {
 	return isColor(value) ? value : new Color(value);
 }
 //#endregion
-//#region src/is.ts
-/**
-* Is the value empty, or only containing `null` or `undefined` values?
-* @param value Value to check
-* @returns `true` if the value is considered empty, otherwise `false`
-*/
-function isEmpty(value) {
-	if (value == null) return true;
-	if (typeof value === "string") return value.length === 0;
-	const values = getArray(value);
-	const { length } = values;
-	for (let index = 0; index < length; index += 1) if (values[index] != null) return false;
-	return true;
-}
-/**
-* Is the value not empty, or holding non-empty values?
-* @param value Value to check
-* @returns `true` if the value is not considered empty, otherwise `false`
-*/
-function isNonEmpty(value) {
-	return !isEmpty(value);
-}
-/**
-* Is the value not `undefined` or `null`?
-* @param value Value to check
-* @returns `true` if the value is not `undefined` or `null`, otherwise `false`
-*/
-function isNonNullable(value) {
-	return value != null;
-}
-/**
-* Is the value not `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
-* @param value Value to check
-* @returns `true` if the value is not `undefined`, `null`, or matches an empty string, otherwise `false`
-*/
-function isNonNullableOrEmpty(value) {
-	return value != null && getString(value) !== "";
-}
-/**
-* Is the value not `undefined`, `null`, or stringified as a whitespace-only string?
-* @param value Value to check
-* @returns `true` if the value is not `undefined`, `null`, or matches a whitespace-only string, otherwise `false`
-*/
-function isNonNullableOrWhitespace(value) {
-	return value != null && !EXPRESSION_WHITESPACE.test(getString(value));
-}
-/**
-* Is the value not a number or a number-like string?
-* @param value Value to check
-* @returns `true` if the value is not a number or a number-like string, otherwise `false`
-*/
-function isNonNumerical(value) {
-	return !isNumerical(value);
-}
-/**
-* Is the value not an object _(or function)_?
-* @param value Value to check
-* @returns `true` if the value is not an object, otherwise `false`
-*/
-function isNonObject(value) {
-	return !isObject(value);
-}
-/**
-* Is the value `undefined` or `null`?
-* @param value Value to check
-* @returns `true` if the value is `undefined` or `null`, otherwise `false`
-*/
-function isNullable(value) {
-	return value == null;
-}
-/**
-* Is the value `undefined`, `null`, or stringified as an empty _(no whitespace)_ string?
-* @param value Value to check
-* @returns `true` if the value is nullable or matches an empty string, otherwise `false`
-*/
-function isNullableOrEmpty(value) {
-	return value == null || getString(value) === "";
-}
-/**
-* Is the value `undefined`, `null`, or stringified as a whitespace-only string?
-* @param value Value to check
-* @returns `true` if the value is nullable or matches a whitespace-only string, otherwise `false`
-*/
-function isNullableOrWhitespace(value) {
-	return value == null || EXPRESSION_WHITESPACE.test(getString(value));
-}
-/**
-* Is the value a number or a number-like string?
-* @param value Value to check
-* @returns `true` if the value is a number or a number-like string, otherwise `false`
-*/
-function isNumerical(value) {
-	return isNumber(value) || typeof value === "string" && value.trim().length > 0 && !Number.isNaN(+value);
-}
-/**
-* Is the value an object _(or function)_?
-* @param value Value to check
-* @returns `true` if the value matches, otherwise `false`
-*/
-function isObject(value) {
-	return typeof value === "object" && value !== null || typeof value === "function";
-}
-const EXPRESSION_WHITESPACE = /^\s*$/;
-//#endregion
 //#region src/logger.ts
 var Logger = class {
 	/**
@@ -4800,4 +4960,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, dedent, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, first, 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, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, last, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, single, 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, dedent, delay, diff, difference, drop, endsWith, endsWithArray, equal, error, exists, filter, find, first, flatten, floor, flow, fromQuery, toPromise as fromResult, toPromise, fuzzy, 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, isNonArrayOrPlainObject, isNonConstructor, isNonEmpty, isNonInstanceOf, isNonKey, isNonNullable, isNonNullableOrEmpty, isNonNullableOrWhitespace, isNonNumber, isNonNumerical, isNonObject, isNonPlainObject, isNonPrimitive, isNonTypedArray, isNullable, isNullableOrEmpty, isNullableOrWhitespace, isNumber, isNumerical, isObject, isOk, isPlainObject, isPrimitive, isRejected, isResult, isRgbColor, isRgbLike, isRgbaColor, isTypedArray, join, kebabCase, last, logger, lowerCase, matchResult, max, median, memoize, merge, min, move, noop, ok, omit, once, parse, partition, pascalCase, pick, pipe, promises, push, queue, range, retry, reverse, rgbToHex, rgbToHsl, rgbToHsla, round, select, setValue, settlePromise, shuffle, single, 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/internal/array/index-of.mjs

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

package/dist/string/fuzzy.d.mts

@@ -0,0 +1,110 @@
+import { PlainObject } from "../models.mjs";
+
+//#region src/string/fuzzy.d.ts
+/**
+ * Fuzzy searcher for an array of items
+ */
+declare class Fuzzy<Item> {
+  #private;
+  /**
+   * Get items currently being searched through
+   */
+  get items(): Item[];
+  /**
+   * Set new items to search through
+   */
+  set items(items: Item[]);
+  /**
+   * Get strings currently being searched through _(the stringified version of `items`)_
+   */
+  get strings(): string[];
+  constructor(state: FuzzyState<Item>);
+  /**
+   * Search for items matching the given value
+   * @param value Value to search for
+   * @param options Search options
+   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   */
+  search(value: string, options?: FuzzyOptions): FuzzyResult<Item>;
+  /**
+   * Search for items matching the given value
+   * @param value Value to search for
+   * @param limit Maximum number of combined items to return in `exact` and `similar`
+   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   */
+  search(value: string, limit: number): FuzzyResult<Item>;
+}
+type FuzzyConfiguration<Item> = {
+  /**
+   * Handler to stringify items
+   *
+   * May be a function that takes an item and returns a string, or if items are plain objects, a key of the item to use to grab a string value from
+   *
+   * Defaults to `getString`
+   */
+  handler?: (item: Item) => string;
+} & (Item extends PlainObject ? {
+  /**
+   * Key to use to stringify items
+   *
+   * Prioritized over `handler`
+   */
+  key?: keyof Item;
+} : {}) & FuzzyOptions;
+type FuzzyOptions = {
+  /**
+   * Maximum number of combined items to return in `exact` and `similar` _(defaults to all matches)_
+   */
+  limit?: number;
+  /**
+   * Maximum score difference between the best and worst similar matches included in results; higher values cast a wider net _(defaults to 5)_
+   */
+  tolerance?: number;
+};
+/**
+ * Search results from a fuzzy search, with exact and similar matches
+ */
+type FuzzyResult<Item> = {
+  /**
+   * Ordered items that exactly match the search value
+   */
+  exact: Item[];
+  /**
+   * Ordered items that are similar to the search value, ranked by relevance
+   */
+  similar: Item[];
+};
+/**
+ * Options for fuzzy searching
+ */
+type FuzzySearchOptions = FuzzyOptions;
+type FuzzyState<Item> = {
+  handler: (item: Item) => string;
+  items: Item[];
+  limit?: number;
+  strings: string[];
+  tolerance: number;
+};
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param key Key to use to stringify items
+ * @returns Fuzzy searcher
+ */
+declare function fuzzy<Item extends PlainObject, ItemKey extends keyof Item>(items: Item[], key?: ItemKey): Fuzzy<Item>;
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param handler Handler to stringify items
+ * @returns Fuzzy searcher
+ */
+declare function fuzzy<Item>(items: Item[], handler?: (item: Item) => string): Fuzzy<Item>;
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param configuration Fuzzy configuration
+ * @returns Fuzzy searcher
+ */
+declare function fuzzy<Item>(items: Item[], configuration?: FuzzyConfiguration<Item>): Fuzzy<Item>;
+//#endregion
+export { FuzzyConfiguration, FuzzyOptions, FuzzyResult, FuzzySearchOptions, fuzzy };

package/dist/string/fuzzy.mjs

@@ -0,0 +1,165 @@
+import { isPlainObject } from "../internal/is.mjs";
+import { getString } from "../internal/string.mjs";
+import { lowerCase } from "./case.mjs";
+import { includes } from "./match.mjs";
+//#region src/string/fuzzy.ts
+/**
+* Fuzzy searcher for an array of items
+*/
+var Fuzzy = class {
+	#state;
+	/**
+	* Get items currently being searched through
+	*/
+	get items() {
+		return this.#state.items.slice();
+	}
+	/**
+	* Set new items to search through
+	*/
+	set items(items) {
+		if (Array.isArray(items)) {
+			this.#state.items = items.slice();
+			this.#state.strings = items.map(this.#state.handler);
+		}
+	}
+	/**
+	* Get strings currently being searched through _(the stringified version of `items`)_
+	*/
+	get strings() {
+		return this.#state.strings.slice();
+	}
+	constructor(state) {
+		this.#state = state;
+	}
+	search(value, options) {
+		return search(this.#state.items, this.#state.strings, value, options == null ? this.#state : getOptions(options, this.#state));
+	}
+};
+function getHandler(input) {
+	if (input == null || input === getString) return getString;
+	switch (typeof input) {
+		case "function": return input;
+		case "string": return (item) => item[input];
+		default:
+			if (isPlainObject(input)) return getHandler(input.key ?? input.handler);
+			throw new TypeError(MESSAGE_HANDLER);
+	}
+}
+function getItems(items) {
+	return items.sort((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
+}
+function getOptions(input, state) {
+	const options = isPlainObject(input) ? input : {};
+	const limit = typeof input === "number" ? input : options.limit;
+	if (typeof limit === "number" && !Number.isNaN(limit) && limit >= 1) options.limit = Math.floor(limit);
+	else options.limit = state?.limit;
+	if (typeof options.tolerance === "number" && !Number.isNaN(options.tolerance)) options.tolerance = options.tolerance < 0 ? 0 : Math.floor(options.tolerance);
+	else options.tolerance = state?.tolerance ?? PROXIMITY_THRESHOLD;
+	return options;
+}
+function getState(items, input) {
+	const handler = getHandler(input);
+	const options = getOptions(input);
+	return {
+		handler,
+		items: items.slice(),
+		limit: options.limit,
+		strings: items.map(handler),
+		tolerance: options.tolerance
+	};
+}
+function fuzzy(items, configuration) {
+	if (!Array.isArray(items)) throw new TypeError(MESSAGE_ARRAY);
+	return new Fuzzy(getState(items, configuration));
+}
+function isSubsequence(haystack, needle) {
+	const lowerCaseHaystack = lowerCase(haystack);
+	const lowerCaseNeedle = lowerCase(needle);
+	const haystackLength = lowerCaseHaystack.length;
+	const needleLength = lowerCaseNeedle.length;
+	let needleIndex = 0;
+	for (let haystackIndex = 0; haystackIndex < haystackLength; haystackIndex += 1) {
+		if (lowerCaseHaystack[haystackIndex] === lowerCaseNeedle[needleIndex]) needleIndex += 1;
+		if (needleIndex === needleLength) return true;
+	}
+	return false;
+}
+function getScore(haystack, needle) {
+	if (!isSubsequence(haystack, needle)) return -1;
+	const lowerCaseHaystack = lowerCase(haystack);
+	const lowerCaseNeedle = lowerCase(needle);
+	const needleLength = lowerCaseNeedle.length;
+	let needleIndex = 0;
+	let previousMatchIndex = -1;
+	let score = 0;
+	for (let haystackIndex = 0; haystackIndex < lowerCaseHaystack.length; haystackIndex += 1) {
+		if (lowerCaseHaystack[haystackIndex] === lowerCaseNeedle[needleIndex]) {
+			score += 1;
+			if (haystackIndex === 0) score += 1;
+			if (previousMatchIndex !== -1) {
+				const gap = haystackIndex - previousMatchIndex - 1;
+				score += Math.max(0, PROXIMITY_THRESHOLD - gap);
+			}
+			previousMatchIndex = haystackIndex;
+			needleIndex += 1;
+		}
+		if (needleIndex === needleLength) break;
+	}
+	score -= Math.floor(lowerCaseHaystack.length / LENGTH_DIVISOR);
+	return Math.max(0, score);
+}
+function search(items, strings, input, options) {
+	const result = {
+		exact: [],
+		similar: []
+	};
+	const value = typeof input === "string" ? input.trim() : "";
+	if (value.length === 0) {
+		result.exact = items.slice(0, options.limit);
+		return result;
+	}
+	let { length } = items;
+	const exact = [];
+	const similar = [];
+	const scored = {};
+	for (let index = 0; index < length; index += 1) {
+		const item = items[index];
+		const haystack = strings[index];
+		if (includes(haystack, value, true)) {
+			exact.push({
+				item,
+				haystack
+			});
+			continue;
+		}
+		const score = getScore(haystack, value);
+		if (score > -1) {
+			scored[score] ??= [];
+			scored[score].push({
+				item,
+				haystack
+			});
+		}
+	}
+	const keys = Object.keys(scored).map(Number).sort((first, second) => second - first);
+	length = keys.length;
+	if (length > 0 && options.tolerance > 0) {
+		const maxScore = keys[0];
+		for (let index = 0; index < length; index += 1) {
+			const key = keys[index];
+			if (maxScore - key > options.tolerance) break;
+			similar.push(...getItems(scored[key]));
+		}
+	}
+	result.exact = getItems(options.limit == null ? exact : exact.slice(0, options.limit));
+	if (options.limit == null) result.similar = similar;
+	else result.similar = similar.slice(0, options.limit - result.exact.length);
+	return result;
+}
+const LENGTH_DIVISOR = 3;
+const MESSAGE_ARRAY = "Fuzzy requires an array of items";
+const MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
+const PROXIMITY_THRESHOLD = 5;
+//#endregion
+export { fuzzy };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.178.0",
+	"version": "0.179.1",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"helper",
@@ -192,6 +192,10 @@
 			"types": "./dist/string/case.d.mts",
 			"default": "./dist/string/case.mjs"
 		},
+		"./string/fuzzy": {
+			"types": "./dist/string/fuzzy.d.mts",
+			"default": "./dist/string/fuzzy.mjs"
+		},
 		"./string/match": {
 			"types": "./dist/string/match.d.mts",
 			"default": "./dist/string/match.mjs"
@@ -253,4 +257,4 @@
 		"vitest": "npm:@voidzero-dev/vite-plus-test@latest"
 	},
 	"packageManager": "npm@11.11.1"
-}
+}

package/src/index.ts

@@ -26,6 +26,7 @@ export * from './internal/value/has';
 export * from './internal/value/set';
 
 export * from './string/case';
+export * from './string/fuzzy';
 export * from './string/index';
 export * from './string/match';
 export * from './string/template';

package/src/internal/array/index-of.ts

@@ -48,7 +48,7 @@ export function indexOf<Item>(
 export function indexOf<Item>(array: Item[], item: Item): number;
 
 export function indexOf(array: unknown[], ...parameters: unknown[]): number {
-	return findValue(FIND_VALUE_INDEX, array, parameters) as number;
+	return findValue(FIND_VALUE_INDEX, array, parameters, false) as number;
 }
 
 // #endregion

package/src/string/fuzzy.ts

@@ -0,0 +1,399 @@
+import {getString} from '../internal/string';
+import {isPlainObject} from '../is';
+import type {PlainObject, RequiredKeys} from '../models';
+import {lowerCase} from './case';
+import {includes} from './match';
+
+// #region Types
+
+/**
+ * Fuzzy searcher for an array of items
+ */
+class Fuzzy<Item> {
+	#state: FuzzyState<Item>;
+
+	/**
+	 * Get items currently being searched through
+	 */
+	get items(): Item[] {
+		return this.#state.items.slice();
+	}
+
+	/**
+	 * Set new items to search through
+	 */
+	set items(items: Item[]) {
+		if (Array.isArray(items)) {
+			this.#state.items = items.slice();
+			this.#state.strings = items.map(this.#state.handler);
+		}
+	}
+
+	/**
+	 * Get strings currently being searched through _(the stringified version of `items`)_
+	 */
+	get strings(): string[] {
+		return this.#state.strings.slice();
+	}
+
+	constructor(state: FuzzyState<Item>) {
+		this.#state = state;
+	}
+
+	/**
+	 * Search for items matching the given value
+	 * @param value Value to search for
+	 * @param options Search options
+	 * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+	 */
+	search(value: string, options?: FuzzyOptions): FuzzyResult<Item>;
+
+	/**
+	 * Search for items matching the given value
+	 * @param value Value to search for
+	 * @param limit Maximum number of combined items to return in `exact` and `similar`
+	 * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+	 */
+	search(value: string, limit: number): FuzzyResult<Item>;
+
+	search(value: string, options?: number | FuzzyOptions): FuzzyResult<Item> {
+		return search(
+			this.#state.items,
+			this.#state.strings,
+			value,
+			options == null ? this.#state : getOptions(options, this.#state),
+		);
+	}
+}
+
+export type FuzzyConfiguration<Item> = {
+	/**
+	 * Handler to stringify items
+	 *
+	 * May be a function that takes an item and returns a string, or if items are plain objects, a key of the item to use to grab a string value from
+	 *
+	 * Defaults to `getString`
+	 */
+	handler?: (item: Item) => string;
+} & (Item extends PlainObject
+	? {
+			/**
+			 * Key to use to stringify items
+			 *
+			 * Prioritized over `handler`
+			 */
+			key?: keyof Item;
+		}
+	: {}) &
+	FuzzyOptions;
+
+type FuzzyItem<Item> = {
+	item: Item;
+	haystack: string;
+};
+
+export type FuzzyOptions = {
+	/**
+	 * Maximum number of combined items to return in `exact` and `similar` _(defaults to all matches)_
+	 */
+	limit?: number;
+	/**
+	 * Maximum score difference between the best and worst similar matches included in results; higher values cast a wider net _(defaults to 5)_
+	 */
+	tolerance?: number;
+};
+
+/**
+ * Search results from a fuzzy search, with exact and similar matches
+ */
+export type FuzzyResult<Item> = {
+	/**
+	 * Ordered items that exactly match the search value
+	 */
+	exact: Item[];
+	/**
+	 * Ordered items that are similar to the search value, ranked by relevance
+	 */
+	similar: Item[];
+};
+
+/**
+ * Options for fuzzy searching
+ */
+export type FuzzySearchOptions = FuzzyOptions;
+
+type FuzzyState<Item> = {
+	handler: (item: Item) => string;
+	items: Item[];
+	limit?: number;
+	strings: string[];
+	tolerance: number;
+};
+
+// #endregion
+
+// #region Functions
+
+function getHandler<Item>(input: unknown): (item: Item) => string {
+	if (input == null || input === getString) {
+		return getString;
+	}
+
+	switch (typeof input) {
+		case 'function':
+			return input as (item: Item) => string;
+
+		case 'string':
+			return (item: Item) => (item as PlainObject)[input] as string;
+
+		default: {
+			if (isPlainObject(input)) {
+				return getHandler(
+					(input as FuzzyConfiguration<PlainObject>).key ??
+						(input as FuzzyConfiguration<Item>).handler,
+				);
+			}
+
+			throw new TypeError(MESSAGE_HANDLER);
+		}
+	}
+}
+
+function getItems<Item>(items: FuzzyItem<Item>[]): Item[] {
+	return items
+		.sort((first, second) => first.haystack.localeCompare(second.haystack))
+		.map(({item}) => item);
+}
+
+function getOptions<Item>(
+	input: unknown,
+	state?: FuzzyState<Item>,
+): RequiredKeys<FuzzyOptions, 'tolerance'> {
+	const options: FuzzyOptions = isPlainObject(input) ? input : {};
+
+	const limit = typeof input === 'number' ? input : options.limit;
+
+	if (typeof limit === 'number' && !Number.isNaN(limit) && limit >= 1) {
+		options.limit = Math.floor(limit);
+	} else {
+		options.limit = state?.limit;
+	}
+
+	if (typeof options.tolerance === 'number' && !Number.isNaN(options.tolerance)) {
+		options.tolerance = options.tolerance < 0 ? 0 : Math.floor(options.tolerance);
+	} else {
+		options.tolerance = state?.tolerance ?? PROXIMITY_THRESHOLD;
+	}
+
+	return options as RequiredKeys<FuzzyOptions, 'tolerance'>;
+}
+
+function getState<Item>(items: Item[], input: unknown): FuzzyState<Item> {
+	const handler = getHandler(input);
+	const options = getOptions(input);
+
+	return {
+		handler,
+		items: items.slice(),
+		limit: options.limit,
+		strings: items.map(handler),
+		tolerance: options.tolerance,
+	};
+}
+
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param key Key to use to stringify items
+ * @returns Fuzzy searcher
+ */
+export function fuzzy<Item extends PlainObject, ItemKey extends keyof Item>(
+	items: Item[],
+	key?: ItemKey,
+): Fuzzy<Item>;
+
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param handler Handler to stringify items
+ * @returns Fuzzy searcher
+ */
+export function fuzzy<Item>(items: Item[], handler?: (item: Item) => string): Fuzzy<Item>;
+
+/**
+ * Create a fuzzy searcher for an array of items
+ * @param items Items to search through
+ * @param configuration Fuzzy configuration
+ * @returns Fuzzy searcher
+ */
+export function fuzzy<Item>(items: Item[], configuration?: FuzzyConfiguration<Item>): Fuzzy<Item>;
+
+export function fuzzy(items: unknown[], configuration?: unknown): Fuzzy<unknown> {
+	if (!Array.isArray(items)) {
+		throw new TypeError(MESSAGE_ARRAY);
+	}
+
+	return new Fuzzy(getState(items, configuration));
+}
+
+function isSubsequence(haystack: string, needle: string): boolean {
+	const lowerCaseHaystack = lowerCase(haystack);
+	const lowerCaseNeedle = lowerCase(needle);
+
+	const haystackLength = lowerCaseHaystack.length;
+	const needleLength = lowerCaseNeedle.length;
+
+	let needleIndex = 0;
+
+	for (let haystackIndex = 0; haystackIndex < haystackLength; haystackIndex += 1) {
+		// Advance needle pointer only on a matching character
+		if (lowerCaseHaystack[haystackIndex] === lowerCaseNeedle[needleIndex]) {
+			needleIndex += 1;
+		}
+
+		// All needle characters matched in order
+		if (needleIndex === needleLength) {
+			return true;
+		}
+	}
+
+	return false;
+}
+
+function getScore(haystack: string, needle: string): number {
+	if (!isSubsequence(haystack, needle)) {
+		return -1;
+	}
+
+	const lowerCaseHaystack = lowerCase(haystack);
+	const lowerCaseNeedle = lowerCase(needle);
+
+	const needleLength = lowerCaseNeedle.length;
+
+	let needleIndex = 0;
+	let previousMatchIndex = -1;
+	let score = 0;
+
+	for (let haystackIndex = 0; haystackIndex < lowerCaseHaystack.length; haystackIndex += 1) {
+		if (lowerCaseHaystack[haystackIndex] === lowerCaseNeedle[needleIndex]) {
+			// +1 for each matched character
+			score += 1;
+
+			// Bonus for matching at the start of the string
+			if (haystackIndex === 0) {
+				score += 1;
+			}
+
+			// Proximity bonus: decays as gap between consecutive matches widens
+			if (previousMatchIndex !== -1) {
+				const gap = haystackIndex - previousMatchIndex - 1;
+
+				score += Math.max(0, PROXIMITY_THRESHOLD - gap);
+			}
+
+			previousMatchIndex = haystackIndex;
+
+			needleIndex += 1;
+		}
+
+		// All needle characters matched; no need to scan further
+		if (needleIndex === needleLength) {
+			break;
+		}
+	}
+
+	// Penalty for longer strings to favour tighter matches
+	score -= Math.floor(lowerCaseHaystack.length / LENGTH_DIVISOR);
+
+	return Math.max(0, score);
+}
+
+function search<Item>(
+	items: Item[],
+	strings: string[],
+	input: string,
+	options: RequiredKeys<FuzzyOptions, 'tolerance'>,
+) {
+	const result: FuzzyResult<Item> = {
+		exact: [],
+		similar: [],
+	};
+
+	const value = typeof input === 'string' ? input.trim() : '';
+
+	if (value.length === 0) {
+		result.exact = items.slice(0, options.limit);
+
+		return result;
+	}
+
+	let {length} = items;
+
+	const exact: Array<FuzzyItem<Item>> = [];
+	const similar: Array<Item> = [];
+
+	const scored: Record<number, Array<FuzzyItem<Item>>> = {};
+
+	for (let index = 0; index < length; index += 1) {
+		const item = items[index];
+		const haystack = strings[index];
+
+		if (includes(haystack, value, true)) {
+			exact.push({item, haystack});
+
+			continue;
+		}
+
+		const score = getScore(haystack, value);
+
+		if (score > -1) {
+			scored[score] ??= [];
+
+			scored[score].push({item, haystack});
+		}
+	}
+
+	const keys = Object.keys(scored)
+		.map(Number)
+		.sort((first, second) => second - first);
+
+	length = keys.length;
+
+	if (length > 0 && options.tolerance > 0) {
+		const maxScore = keys[0];
+
+		for (let index = 0; index < length; index += 1) {
+			const key = keys[index];
+
+			if (maxScore - key > options.tolerance) {
+				break;
+			}
+
+			similar.push(...getItems(scored[key]));
+		}
+	}
+
+	result.exact = getItems(options.limit == null ? exact : exact.slice(0, options.limit));
+
+	if (options.limit == null) {
+		result.similar = similar;
+	} else {
+		result.similar = similar.slice(0, options.limit - result.exact.length);
+	}
+
+	return result;
+}
+
+// #endregion
+
+// #region Variables
+
+const LENGTH_DIVISOR = 3;
+
+const MESSAGE_ARRAY = 'Fuzzy requires an array of items';
+
+const MESSAGE_HANDLER = 'Fuzzy requires a key or function to stringify items';
+
+const PROXIMITY_THRESHOLD = 5;
+
+// #endregion