@oscarpalmer/atoms 0.219.0 → 0.220.0

package/dist/index.d.mts

@@ -6367,26 +6367,28 @@ type Fuzzy<Item> = {
    *
    * @param value Value to search for
    * @param options Search options
-   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   * @returns Search results, with exact, included, and similar matches
    */
   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)_
+   * @param limit Maximum number of combined items to return in `exact`, `included`, and `similar`
+   * @returns Search results, with exact, included, and similar matches
    */
   search(value: string, limit: number): FuzzyResult<Item>;
 };
 type FuzzyConfiguration<Item> = {
+  handler?: (item: Item) => string;
   /**
-   * Handler to stringify items
+   * Function to compare the stringified items for results _(defaults to `Intl.Collator().compare`)_
    *
-   * - 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`
+   * @param first First string to compare
+   * @param second Second string to compare
+   * @returns Comparison result, similar to `Array.prototype.sort` callback
    */
-  handler?: (item: Item) => string;
+  compare?: (first: string, second: string) => number;
 } & (Item extends PlainObject ? {
   /**
    * Key to use to stringify items
@@ -6395,13 +6397,13 @@ type FuzzyConfiguration<Item> = {
    */
   key?: keyof Item;
 } : {}) & FuzzyOptions;
-type FuzzyItem<Item> = {
-  item: Item;
-  haystack: string;
+type FuzzyItem<Data> = {
+  data: Data;
+  string: FuzzyString;
 };
 type FuzzyOptions = {
   /**
-   * Maximum number of combined items to return in `exact` and `similar` _(defaults to all matches)_
+   * Maximum number of combined items to return in `exact`, `included`, and `similar` _(defaults to all matches)_
    */
   limit?: number;
   /**
@@ -6412,29 +6414,56 @@ type FuzzyOptions = {
    */
   tolerance?: number;
 };
+type FuzzyRanked<Data> = {
+  position: number;
+  /**
+   * `0` for starting with the value, `1` for the value starting a word, `2` for anything else
+   */
+  rank: number;
+} & FuzzyItem<Data>;
 /**
- * Search results from a fuzzy search, with exact and similar matches
+ * Search results from a fuzzy search, with exact, included, and similar matches
  */
 type FuzzyResult<Item> = {
   /**
-   * Ordered items that exactly match the search value
+   * Items whose strings exactly match the search value, ordered alphabetically
    */
   exact: Item[];
   /**
-   * Ordered items that are similar to the search value, ranked by relevance
+   * Items whose strings contain the search value, ordered alphabetically
+   */
+  included: Item[];
+  /**
+   * Items whose strings are similar to the search value, ranked by relevance, sorted by score, and ordered alphabetically within the same score
    */
   similar: Item[];
 };
 type FuzzyState<Item> = {
+  compare: FuzzyStateCompare<Item>;
   handler(item: Item): string;
-  items: Item[];
-  limit?: number;
-  strings: string[];
+  items: FuzzyStateItems<Item>;
+  limit: number;
   tolerance: number;
 };
+type FuzzyStateCompare<Item = unknown> = {
+  item: (first: FuzzyItem<Item>, second: FuzzyItem<Item>) => number;
+  ranked: (first: FuzzyRanked<Item>, second: FuzzyRanked<Item>) => number;
+};
+type FuzzyStateItems<Item> = {
+  original: Array<FuzzyItem<Item>>;
+  sorted?: Array<FuzzyItem<Item>>;
+};
+type FuzzyString = {
+  lowercase: string;
+  original: string;
+};
+type InternalFuzzy<Item = unknown> = {
+  [FUZZY_SYMBOL]: FuzzyState<Item>;
+} & Fuzzy<Item>;
+declare const FUZZY_SYMBOL: unique symbol;
 //#endregion
 //#region src/string/fuzzy.d.ts
-declare function Fuzzy(this: any, state: FuzzyState<unknown>): void;
+declare function Fuzzy(this: InternalFuzzy, state: FuzzyState<unknown>): void;
 /**
  * Create a fuzzy searcher for an array of items
  *
@@ -9453,4 +9482,4 @@ export declare class SizedSet<Value = unknown> extends Set<Value> {
   get(value: Value, update?: boolean): Value | undefined;
 }
 //#endregion
-export { type ArrayComparisonSorter, type ArrayKeySorter, type ArrayKeySorters, type ArraySorter, type ArraySorters, type ArrayValueSorter, type Asserter, type AssignOptions, type Assigner, type AsyncFailure, type AsyncFlow, type AsyncLimiter, type AsyncOnce, type AsyncPlan, type AsyncPlanned, type AsyncStep, type AsyncSuccess, type Beacon, type BeaconOptions, type CloneOptions, type Cloner, type Color, type ColorType, type ColorTypeExtended, type ColorValue, type ColorValueExtended, type CompareCallback, type ComparisonSorter, type DiffOptions, type DiffResult, type EqualOptions, type Equalizer, type Failure, type Flow, type FulfilledPromise, type Fuzzy, type FuzzyItem, type FuzzyOptions, type FuzzyResult, type HSLAColor, type HSLColor, type HWBAColor, type HWBColor, type Herald, type HeraldEvents, type HeraldOptions, Key$1 as Key, type KeyedQueue, type Limiter, Logger, type Memoized, type MemoizedOptions, type MergeOptions, type Merger, type NormalizeOptions, type Normalizer, type Observable, type Observer, type Once, type Plan, type PlanError, type PlanOk, type PlanReturned, type Planned, type PromiseOptions, type PromiseStrategy, type PromisesOptions, type Queue, type QueueOptions, type Queued, type RGBAColor, type RGBColor, type RejectedPromise, type Renderer, type Shaken, type Smushed, type SortDirection, type Sorter, type Step, type Subscription, type SubscriptionParameters, type SubscriptionProperty, type Subscriptions, type SubscriptionsParameters, type Success, type TemplateOptions, type Templater, type TemplaterOptions, type TemplaterRenderer, type TimeLogger, type TransformCallback, type TransformCallbacks, type Transformer, type Unsmushed, push as append, filterAndMap as select, toPromise as fromResult, getRandomFloatingNumber as getRandomFloat, isLogger, isTimeLogger, mapAndFilter as reverseSelect };
+export { type ArrayComparisonSorter, type ArrayKeySorter, type ArrayKeySorters, type ArraySorter, type ArraySorters, type ArrayValueSorter, type Asserter, type AssignOptions, type Assigner, type AsyncFailure, type AsyncFlow, type AsyncLimiter, type AsyncOnce, type AsyncPlan, type AsyncPlanned, type AsyncStep, type AsyncSuccess, type Beacon, type BeaconOptions, type CloneOptions, type Cloner, type Color, type ColorType, type ColorTypeExtended, type ColorValue, type ColorValueExtended, type CompareCallback, type ComparisonSorter, type DiffOptions, type DiffResult, type EqualOptions, type Equalizer, type Failure, type Flow, type FulfilledPromise, type Fuzzy, type FuzzyOptions, type FuzzyResult, type HSLAColor, type HSLColor, type HWBAColor, type HWBColor, type Herald, type HeraldEvents, type HeraldOptions, Key$1 as Key, type KeyedQueue, type Limiter, Logger, type Memoized, type MemoizedOptions, type MergeOptions, type Merger, type NormalizeOptions, type Normalizer, type Observable, type Observer, type Once, type Plan, type PlanError, type PlanOk, type PlanReturned, type Planned, type PromiseOptions, type PromiseStrategy, type PromisesOptions, type Queue, type QueueOptions, type Queued, type RGBAColor, type RGBColor, type RejectedPromise, type Renderer, type Shaken, type Smushed, type SortDirection, type Sorter, type Step, type Subscription, type SubscriptionParameters, type SubscriptionProperty, type Subscriptions, type SubscriptionsParameters, type Success, type TemplateOptions, type Templater, type TemplaterOptions, type TemplaterRenderer, type TimeLogger, type TransformCallback, type TransformCallbacks, type Transformer, type Unsmushed, push as append, filterAndMap as select, toPromise as fromResult, getRandomFloatingNumber as getRandomFloat, isLogger, isTimeLogger, mapAndFilter as reverseSelect };

package/dist/index.mjs

@@ -3728,79 +3728,12 @@ function attemptPipe(initial, first, ...seconds) {
 attemptPipe.async = attemptAsyncPipe;
 //#endregion
 //#region src/models/string/string.fuzzy.model.ts
+const FUZZY_BOUNDARY_SEPARATOR = /[\s./:\\_-]/;
 const FUZZY_MESSAGE_ARRAY = "Fuzzy requires an array of items";
 const FUZZY_MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
 const FUZZY_PROPERTY = "$fuzzy";
 const FUZZY_SYMBOL = Symbol(FUZZY_PROPERTY);
 //#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`
-*
-* @example
-* ```typescript
-* endsWith('this is a test', 'test');          // => true
-* endsWith('this is a test', 'Test');          // => false
-* endsWith('this is a test', 'Test', true);    // => true
-* endsWith('this is a test', 'not');           // => false
-* ```
-*/
-function endsWith(haystack, needle, ignoreCase) {
-	return match(STRING_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`
-*
-* @example
-* ```typescript
-* includes('this is a test', 'is');          // => true
-* includes('this is a test', 'Is');          // => false
-* includes('this is a test', 'Is', true);    // => true
-* includes('this is a test', 'not');         // => false
-* ```
-*/
-function includes(haystack, needle, ignoreCase) {
-	return match(STRING_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`
-*
-* @example
-* ```typescript
-* startsWith('this is a test', 'this');          // => true
-* startsWith('this is a test', 'This');          // => false
-* startsWith('this is a test', 'This', true);    // => true
-* startsWith('this is a test', 'not');           // => false
-* ```
-*/
-function startsWith(haystack, needle, ignoreCase) {
-	return match(STRING_MATCH_STARTS_WITH, haystack, needle, ignoreCase === true);
-}
-const matchMemoizers = {};
-//#endregion
 //#region src/string/fuzzy.ts
 function Fuzzy(state) {
 	this[FUZZY_SYMBOL] = state;
@@ -3810,39 +3743,76 @@ Fuzzy.prototype.search = search;
 Object.defineProperties(Fuzzy.prototype, {
 	items: {
 		enumerable: true,
-		get: getFuzzyItems,
-		set: setFuzzyItems
+		get: getItems,
+		set: setItems
 	},
 	strings: {
 		enumerable: true,
-		get: getFuzzyStrings
+		get: getStrings
 	}
 });
-function createFuzzyItems(items) {
-	return items.toSorted((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
+function compareItem(sorter) {
+	return (first, second) => sorter(first.string.original, second.string.original);
 }
-function createFuzzyOptions(input, state) {
-	const options = isPlainObject(input) ? input : {};
-	const limit = typeof input === "number" ? input : options.limit;
+function compareRanked(sorter) {
+	return (first, second) => first.rank - second.rank || first.position - second.position || sorter(first.string.original, second.string.original);
+}
+function createItems(state, items) {
+	state.items.original = items.map((item) => ({
+		data: item,
+		string: createString(state.handler(item))
+	}));
+	state.items.sorted = void 0;
+}
+function createOptions(input, state) {
+	const options = {};
+	const original = isPlainObject(input) ? input : {};
+	const limit = typeof input === "number" ? input : original.limit;
 	if (typeof limit === "number" && !Number.isNaN(limit) && limit >= 1) options.limit = floor(limit);
-	else options.limit = state?.limit;
-	options.tolerance = getTolerance(options.tolerance, state);
+	else options.limit = state?.limit ?? Number.POSITIVE_INFINITY;
+	options.tolerance = getTolerance(original.tolerance, state);
 	return options;
 }
-function createFuzzyState(items, input) {
-	const handler = getHandler(input);
-	const options = createFuzzyOptions(input);
+function createRanked(item, needle, position) {
+	let boundary = position;
+	while (boundary > -1 && !isBoundary(item.string, boundary)) boundary = item.string.lowercase.indexOf(needle, boundary + 1);
+	if (boundary === -1) return {
+		...item,
+		position,
+		rank: 2
+	};
 	return {
+		...item,
+		position: boundary,
+		rank: boundary === 0 ? 0 : 1
+	};
+}
+function createState(items, input) {
+	const handler = getHandler(input);
+	const options = createOptions(input);
+	const sorter = getComparator(input);
+	const state = {
+		compare: {
+			item: compareItem(sorter),
+			ranked: compareRanked(sorter)
+		},
 		handler,
-		items: items.slice(),
+		items: { original: [] },
 		limit: options.limit,
-		strings: items.map(handler),
 		tolerance: options.tolerance
 	};
+	createItems(state, items);
+	return state;
+}
+function createString(original) {
+	return {
+		original,
+		lowercase: lowerCase(original)
+	};
 }
 function fuzzy(items, configuration) {
 	if (!Array.isArray(items)) throw new TypeError(FUZZY_MESSAGE_ARRAY);
-	return new Fuzzy(createFuzzyState(items, configuration));
+	return new Fuzzy(createState(items, configuration));
 }
 /**
 * Does the needle match the haystack in a fuzzy way?
@@ -3856,53 +3826,117 @@ function fuzzy(items, configuration) {
 function fuzzyMatch(haystack, needle) {
 	if (typeof haystack !== "string" || typeof needle !== "string") return false;
 	const trimmed = needle.trim();
-	if (includes(haystack, trimmed, true)) return true;
-	return getScore(haystack, trimmed) > -1;
+	const lowercaseHaystack = lowerCase(haystack);
+	const lowercaseNeedle = lowerCase(trimmed);
+	if (lowercaseHaystack.includes(lowercaseNeedle)) return true;
+	return getScore({
+		lowercase: lowercaseHaystack,
+		original: haystack
+	}, lowercaseNeedle) > -1;
+}
+function getComparator(input) {
+	if (isPlainObject(input) && typeof input.compare === "function") return input.compare;
+	defaultSorter ??= Intl.Collator().compare;
+	return defaultSorter;
 }
 function getHandler(input) {
 	if (input == null || input === getString) return getString;
 	switch (typeof input) {
-		case "function": return input;
-		case "string": return (item) => item[input];
+		case "function": return (item) => getString(input(item));
+		case "number":
+		case "string":
+		case "symbol": return (item) => getString(item?.[input]);
 		default:
 			if (isPlainObject(input)) return getHandler(input.key ?? input.handler);
 			throw new TypeError(FUZZY_MESSAGE_HANDLER);
 	}
 }
-function getFuzzyItems() {
-	return this[FUZZY_SYMBOL].items.slice();
-}
-function getFuzzyStrings() {
-	return this[FUZZY_SYMBOL].strings.slice();
+function getItems() {
+	return this[FUZZY_SYMBOL].items.original.map((item) => item.data);
 }
-function getScore(haystack, needle) {
-	if (!isSubsequence(haystack, needle)) return -1;
-	const lowerCaseHaystack = lowerCase(haystack);
-	const lowerCaseNeedle = lowerCase(needle);
-	const needleLength = lowerCaseNeedle.length;
+function getMatchEnd(haystack, needle, cursor) {
+	const haystackLength = haystack.length;
+	const needleLength = needle.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 += max([0, 5 - gap]);
+	for (let index = cursor; index < haystackLength; index += 1) if (haystack[index] === needle[needleIndex]) {
+		needleIndex += 1;
+		if (needleIndex === needleLength) return index;
+	}
+	return -1;
+}
+function getResult(state, exact, included, scored, options) {
+	const result = {
+		exact: [],
+		included: [],
+		similar: []
+	};
+	exact.sort(state.compare.item);
+	result.exact = exact.slice(0, options.limit).map((item) => item.data);
+	included.sort(state.compare.ranked);
+	result.included = included.slice(0, options.limit - result.exact.length).map((item) => item.data);
+	const remaining = options.limit - result.exact.length - result.included.length;
+	if (remaining === 0) return result;
+	const keys = Object.keys(scored).map(Number).sort((first, second) => second - first);
+	const keysLength = keys.length;
+	if (keysLength === 0) return result;
+	const maxScore = keys[0];
+	outer: for (let index = 0; index < keysLength; index += 1) {
+		const key = keys[index];
+		if (maxScore - key > options.tolerance) break;
+		const keyed = scored[key];
+		const keyedLength = keyed.length;
+		keyed.sort(state.compare.item);
+		for (let keyedIndex = 0; keyedIndex < keyedLength; keyedIndex += 1) {
+			result.similar.push(keyed[keyedIndex].data);
+			if (result.similar.length >= remaining) break outer;
+		}
+	}
+	return result;
+}
+function getScore(item, needle) {
+	const haystackLength = item.lowercase.length;
+	const needleLength = needle.length;
+	if (needleLength > haystackLength) return -1;
+	let best = -1;
+	let cursor = 0;
+	while (cursor < haystackLength) {
+		const end = getMatchEnd(item.lowercase, needle, cursor);
+		if (end === -1) break;
+		let index = end;
+		let needleIndex = needleLength - 1;
+		let next = -1;
+		let score = 0;
+		let start = end;
+		while (needleIndex >= 0) {
+			if (item.lowercase[index] === needle[needleIndex]) {
+				score += 1;
+				if (next !== -1) score += max([0, 5 - (next - index - 1)]);
+				if (isBoundary(item, index)) score += 2;
+				next = index;
+				start = index;
+				needleIndex -= 1;
 			}
-			previousMatchIndex = haystackIndex;
-			needleIndex += 1;
+			index -= 1;
 		}
-		if (needleIndex === needleLength) break;
+		if (start === 0) score += 1;
+		if (score > best) best = score;
+		cursor = start + 1;
 	}
-	score -= floor(lowerCaseHaystack.length / 3);
-	return max([0, score]);
+	if (best === -1) return -1;
+	return max([0, best - floor(haystackLength / 3)]);
+}
+function getStrings() {
+	return this[FUZZY_SYMBOL].items.original.map((item) => item.string.original);
 }
 function getTolerance(input, state) {
 	if (typeof input === "number" && !Number.isNaN(input)) return input < 0 ? 0 : floor(input);
 	return state?.tolerance ?? 5;
 }
+function isBoundary(string, index) {
+	if (index === 0 || FUZZY_BOUNDARY_SEPARATOR.test(string.lowercase[index - 1])) return true;
+	if (string.original.length !== string.lowercase.length) return false;
+	return string.original[index] !== string.lowercase[index] && string.original[index - 1] === string.lowercase[index - 1];
+}
 /**
 * Is the value a fuzzy searcher?
 *
@@ -3914,74 +3948,48 @@ function getTolerance(input, state) {
 function isFuzzy(value) {
 	return typeof value === "object" && value !== null && "$fuzzy" in value && value["$fuzzy"] === true;
 }
-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 search(input, option) {
 	const state = this[FUZZY_SYMBOL];
-	const options = option == null ? state : createFuzzyOptions(option, state);
-	const result = {
-		exact: [],
-		similar: []
-	};
+	const options = option == null ? state : createOptions(option, state);
 	const value = typeof input === "string" ? input.trim() : "";
+	const lowercaseValue = lowerCase(value);
 	if (value.length === 0) {
-		result.exact = state.items.slice(0, options.limit);
-		return result;
+		state.items.sorted ??= state.items.original.toSorted(state.compare.item);
+		return {
+			exact: state.items.sorted.slice(0, options.limit).map((item) => item.data),
+			included: [],
+			similar: []
+		};
 	}
-	let { length } = state.items;
 	const exact = [];
-	const similar = [];
+	const included = [];
 	const scored = {};
+	const { length } = state.items.original;
 	for (let index = 0; index < length; index += 1) {
-		const item = state.items[index];
-		const haystack = state.strings[index];
-		if (includes(haystack, value, true)) {
-			exact.push({
-				item,
-				haystack
-			});
+		const item = state.items.original[index];
+		const { string } = item;
+		if (string.lowercase === lowercaseValue) {
+			exact.push(item);
 			continue;
 		}
-		const score = getScore(haystack, value);
+		const position = string.lowercase.indexOf(lowercaseValue);
+		if (position > -1) {
+			included.push(createRanked(item, lowercaseValue, position));
+			continue;
+		}
+		const score = getScore(string, lowercaseValue);
 		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(...createFuzzyItems(scored[key]));
+			scored[score].push(item);
 		}
 	}
-	result.exact = createFuzzyItems(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;
+	return getResult(state, exact, included, scored, options);
 }
-function setFuzzyItems(value) {
+function setItems(value) {
 	if (!Array.isArray(value)) throw new TypeError(FUZZY_MESSAGE_ARRAY);
-	const state = this[FUZZY_SYMBOL];
-	state.items = value.slice();
-	state.strings = value.map((item) => state.handler(item));
+	createItems(this[FUZZY_SYMBOL], value);
 }
+let defaultSorter;
 fuzzy.is = isFuzzy;
 fuzzy.match = fuzzyMatch;
 //#endregion
@@ -4089,6 +4097,74 @@ function truncate(value, length, suffix) {
 	return `${value.slice(0, truncatedLength)}${actualSuffix}`;
 }
 //#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`
+*
+* @example
+* ```typescript
+* endsWith('this is a test', 'test');          // => true
+* endsWith('this is a test', 'Test');          // => false
+* endsWith('this is a test', 'Test', true);    // => true
+* endsWith('this is a test', 'not');           // => false
+* ```
+*/
+function endsWith(haystack, needle, ignoreCase) {
+	return match(STRING_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`
+*
+* @example
+* ```typescript
+* includes('this is a test', 'is');          // => true
+* includes('this is a test', 'Is');          // => false
+* includes('this is a test', 'Is', true);    // => true
+* includes('this is a test', 'not');         // => false
+* ```
+*/
+function includes(haystack, needle, ignoreCase) {
+	return match(STRING_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`
+*
+* @example
+* ```typescript
+* startsWith('this is a test', 'this');          // => true
+* startsWith('this is a test', 'This');          // => false
+* startsWith('this is a test', 'This', true);    // => true
+* startsWith('this is a test', 'not');           // => false
+* ```
+*/
+function startsWith(haystack, needle, ignoreCase) {
+	return match(STRING_MATCH_STARTS_WITH, haystack, needle, ignoreCase === true);
+}
+const matchMemoizers = {};
+//#endregion
 //#region src/models/string/string.normalize.model.ts
 const NORMALIZE_DEBURR_CHARACTERS = {
 	Æ: "AE",

package/dist/models/string/string.fuzzy.model.d.mts

@@ -27,26 +27,28 @@ export type Fuzzy<Item> = {
    *
    * @param value Value to search for
    * @param options Search options
-   * @returns Search results, with exact matches _(ordered)_ and similar matches _(ordered by relevance)_
+   * @returns Search results, with exact, included, and similar matches
    */
   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)_
+   * @param limit Maximum number of combined items to return in `exact`, `included`, and `similar`
+   * @returns Search results, with exact, included, and similar matches
    */
   search(value: string, limit: number): FuzzyResult<Item>;
 };
 export type FuzzyConfiguration<Item> = {
+  handler?: (item: Item) => string;
   /**
-   * Handler to stringify items
+   * Function to compare the stringified items for results _(defaults to `Intl.Collator().compare`)_
    *
-   * - 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`
+   * @param first First string to compare
+   * @param second Second string to compare
+   * @returns Comparison result, similar to `Array.prototype.sort` callback
    */
-  handler?: (item: Item) => string;
+  compare?: (first: string, second: string) => number;
 } & (Item extends PlainObject ? {
   /**
    * Key to use to stringify items
@@ -55,13 +57,13 @@ export type FuzzyConfiguration<Item> = {
    */
   key?: keyof Item;
 } : {}) & FuzzyOptions;
-export type FuzzyItem<Item> = {
-  item: Item;
-  haystack: string;
+export type FuzzyItem<Data> = {
+  data: Data;
+  string: FuzzyString;
 };
 export type FuzzyOptions = {
   /**
-   * Maximum number of combined items to return in `exact` and `similar` _(defaults to all matches)_
+   * Maximum number of combined items to return in `exact`, `included`, and `similar` _(defaults to all matches)_
    */
   limit?: number;
   /**
@@ -72,16 +74,27 @@ export type FuzzyOptions = {
    */
   tolerance?: number;
 };
+export type FuzzyRanked<Data> = {
+  position: number;
+  /**
+   * `0` for starting with the value, `1` for the value starting a word, `2` for anything else
+   */
+  rank: number;
+} & FuzzyItem<Data>;
 /**
- * Search results from a fuzzy search, with exact and similar matches
+ * Search results from a fuzzy search, with exact, included, and similar matches
  */
 export type FuzzyResult<Item> = {
   /**
-   * Ordered items that exactly match the search value
+   * Items whose strings exactly match the search value, ordered alphabetically
    */
   exact: Item[];
   /**
-   * Ordered items that are similar to the search value, ranked by relevance
+   * Items whose strings contain the search value, ordered alphabetically
+   */
+  included: Item[];
+  /**
+   * Items whose strings are similar to the search value, ranked by relevance, sorted by score, and ordered alphabetically within the same score
    */
   similar: Item[];
 };
@@ -90,19 +103,34 @@ export type FuzzyResult<Item> = {
  */
 export type FuzzySearchOptions = { [Key in keyof FuzzyOptions]: FuzzyOptions[Key]; };
 export type FuzzyState<Item> = {
+  compare: FuzzyStateCompare<Item>;
   handler(item: Item): string;
-  items: Item[];
-  limit?: number;
-  strings: string[];
+  items: FuzzyStateItems<Item>;
+  limit: number;
   tolerance: number;
 };
+type FuzzyStateCompare<Item = unknown> = {
+  item: (first: FuzzyItem<Item>, second: FuzzyItem<Item>) => number;
+  ranked: (first: FuzzyRanked<Item>, second: FuzzyRanked<Item>) => number;
+};
+type FuzzyStateItems<Item> = {
+  original: Array<FuzzyItem<Item>>;
+  sorted?: Array<FuzzyItem<Item>>;
+};
+export type FuzzyString = {
+  lowercase: string;
+  original: string;
+};
 export type InternalFuzzy<Item = unknown> = {
   [FUZZY_SYMBOL]: FuzzyState<Item>;
 } & Fuzzy<Item>;
+export declare const FUZZY_BOUNDARY_BONUS = 2;
+export declare const FUZZY_BOUNDARY_SEPARATOR: RegExp;
 export declare const FUZZY_LENGTH_DIVISOR = 3;
 export declare const FUZZY_MESSAGE_ARRAY = "Fuzzy requires an array of items";
 export declare const FUZZY_MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
 export declare const FUZZY_PROPERTY = "$fuzzy";
 export declare const FUZZY_PROXIMITY_THRESHOLD = 5;
 export declare const FUZZY_SYMBOL: unique symbol;
-//#endregion
+//#endregion
+export {};

package/dist/models/string/string.fuzzy.model.mjs

@@ -1,4 +1,6 @@
 //#region src/models/string/string.fuzzy.model.ts
+const FUZZY_BOUNDARY_BONUS = 2;
+const FUZZY_BOUNDARY_SEPARATOR = /[\s./:\\_-]/;
 const FUZZY_LENGTH_DIVISOR = 3;
 const FUZZY_MESSAGE_ARRAY = "Fuzzy requires an array of items";
 const FUZZY_MESSAGE_HANDLER = "Fuzzy requires a key or function to stringify items";
@@ -6,4 +8,4 @@ const FUZZY_PROPERTY = "$fuzzy";
 const FUZZY_PROXIMITY_THRESHOLD = 5;
 const FUZZY_SYMBOL = Symbol(FUZZY_PROPERTY);
 //#endregion
-export { FUZZY_LENGTH_DIVISOR, FUZZY_MESSAGE_ARRAY, FUZZY_MESSAGE_HANDLER, FUZZY_PROPERTY, FUZZY_PROXIMITY_THRESHOLD, FUZZY_SYMBOL };
+export { FUZZY_BOUNDARY_BONUS, FUZZY_BOUNDARY_SEPARATOR, FUZZY_LENGTH_DIVISOR, FUZZY_MESSAGE_ARRAY, FUZZY_MESSAGE_HANDLER, FUZZY_PROPERTY, FUZZY_PROXIMITY_THRESHOLD, FUZZY_SYMBOL };

package/dist/string/fuzzy.d.mts

@@ -1,7 +1,7 @@
 import { PlainObject } from "../models/index.mjs";
-import { Fuzzy, FuzzyConfiguration, FuzzyItem, FuzzyOptions, FuzzyResult, FuzzyState } from "../models/string/string.fuzzy.model.mjs";
+import { Fuzzy, FuzzyConfiguration, FuzzyOptions, FuzzyResult, FuzzyState, InternalFuzzy } from "../models/string/string.fuzzy.model.mjs";
 //#region src/string/fuzzy.d.ts
-declare function Fuzzy(this: any, state: FuzzyState<unknown>): void;
+declare function Fuzzy(this: InternalFuzzy, state: FuzzyState<unknown>): void;
 /**
  * Create a fuzzy searcher for an array of items
  *
@@ -50,4 +50,4 @@ export declare namespace fuzzy {
   export var match: typeof fuzzyMatch;
 }
 //#endregion
-export type { Fuzzy, FuzzyItem, FuzzyOptions, FuzzyResult };
+export type { Fuzzy, FuzzyOptions, FuzzyResult };

package/dist/string/fuzzy.mjs

@@ -3,8 +3,7 @@ import { floor } from "../internal/math/misc.mjs";
 import { max } from "../internal/math/aggregate.mjs";
 import { getString } from "../internal/string/misc.mjs";
 import { lowerCase } from "../internal/string/case.mjs";
-import { FUZZY_MESSAGE_ARRAY, FUZZY_MESSAGE_HANDLER, FUZZY_PROPERTY, FUZZY_SYMBOL } from "../models/string/string.fuzzy.model.mjs";
-import { includes } from "./match.mjs";
+import { FUZZY_BOUNDARY_SEPARATOR, FUZZY_MESSAGE_ARRAY, FUZZY_MESSAGE_HANDLER, FUZZY_PROPERTY, FUZZY_SYMBOL } from "../models/string/string.fuzzy.model.mjs";
 //#region src/string/fuzzy.ts
 function Fuzzy(state) {
 	this[FUZZY_SYMBOL] = state;
@@ -14,39 +13,76 @@ Fuzzy.prototype.search = search;
 Object.defineProperties(Fuzzy.prototype, {
 	items: {
 		enumerable: true,
-		get: getFuzzyItems,
-		set: setFuzzyItems
+		get: getItems,
+		set: setItems
 	},
 	strings: {
 		enumerable: true,
-		get: getFuzzyStrings
+		get: getStrings
 	}
 });
-function createFuzzyItems(items) {
-	return items.toSorted((first, second) => first.haystack.localeCompare(second.haystack)).map(({ item }) => item);
+function compareItem(sorter) {
+	return (first, second) => sorter(first.string.original, second.string.original);
 }
-function createFuzzyOptions(input, state) {
-	const options = isPlainObject(input) ? input : {};
-	const limit = typeof input === "number" ? input : options.limit;
+function compareRanked(sorter) {
+	return (first, second) => first.rank - second.rank || first.position - second.position || sorter(first.string.original, second.string.original);
+}
+function createItems(state, items) {
+	state.items.original = items.map((item) => ({
+		data: item,
+		string: createString(state.handler(item))
+	}));
+	state.items.sorted = void 0;
+}
+function createOptions(input, state) {
+	const options = {};
+	const original = isPlainObject(input) ? input : {};
+	const limit = typeof input === "number" ? input : original.limit;
 	if (typeof limit === "number" && !Number.isNaN(limit) && limit >= 1) options.limit = floor(limit);
-	else options.limit = state?.limit;
-	options.tolerance = getTolerance(options.tolerance, state);
+	else options.limit = state?.limit ?? Number.POSITIVE_INFINITY;
+	options.tolerance = getTolerance(original.tolerance, state);
 	return options;
 }
-function createFuzzyState(items, input) {
-	const handler = getHandler(input);
-	const options = createFuzzyOptions(input);
+function createRanked(item, needle, position) {
+	let boundary = position;
+	while (boundary > -1 && !isBoundary(item.string, boundary)) boundary = item.string.lowercase.indexOf(needle, boundary + 1);
+	if (boundary === -1) return {
+		...item,
+		position,
+		rank: 2
+	};
 	return {
+		...item,
+		position: boundary,
+		rank: boundary === 0 ? 0 : 1
+	};
+}
+function createState(items, input) {
+	const handler = getHandler(input);
+	const options = createOptions(input);
+	const sorter = getComparator(input);
+	const state = {
+		compare: {
+			item: compareItem(sorter),
+			ranked: compareRanked(sorter)
+		},
 		handler,
-		items: items.slice(),
+		items: { original: [] },
 		limit: options.limit,
-		strings: items.map(handler),
 		tolerance: options.tolerance
 	};
+	createItems(state, items);
+	return state;
+}
+function createString(original) {
+	return {
+		original,
+		lowercase: lowerCase(original)
+	};
 }
 function fuzzy(items, configuration) {
 	if (!Array.isArray(items)) throw new TypeError(FUZZY_MESSAGE_ARRAY);
-	return new Fuzzy(createFuzzyState(items, configuration));
+	return new Fuzzy(createState(items, configuration));
 }
 /**
 * Does the needle match the haystack in a fuzzy way?
@@ -60,53 +96,117 @@ function fuzzy(items, configuration) {
 function fuzzyMatch(haystack, needle) {
 	if (typeof haystack !== "string" || typeof needle !== "string") return false;
 	const trimmed = needle.trim();
-	if (includes(haystack, trimmed, true)) return true;
-	return getScore(haystack, trimmed) > -1;
+	const lowercaseHaystack = lowerCase(haystack);
+	const lowercaseNeedle = lowerCase(trimmed);
+	if (lowercaseHaystack.includes(lowercaseNeedle)) return true;
+	return getScore({
+		lowercase: lowercaseHaystack,
+		original: haystack
+	}, lowercaseNeedle) > -1;
+}
+function getComparator(input) {
+	if (isPlainObject(input) && typeof input.compare === "function") return input.compare;
+	defaultSorter ??= Intl.Collator().compare;
+	return defaultSorter;
 }
 function getHandler(input) {
 	if (input == null || input === getString) return getString;
 	switch (typeof input) {
-		case "function": return input;
-		case "string": return (item) => item[input];
+		case "function": return (item) => getString(input(item));
+		case "number":
+		case "string":
+		case "symbol": return (item) => getString(item?.[input]);
 		default:
 			if (isPlainObject(input)) return getHandler(input.key ?? input.handler);
 			throw new TypeError(FUZZY_MESSAGE_HANDLER);
 	}
 }
-function getFuzzyItems() {
-	return this[FUZZY_SYMBOL].items.slice();
-}
-function getFuzzyStrings() {
-	return this[FUZZY_SYMBOL].strings.slice();
+function getItems() {
+	return this[FUZZY_SYMBOL].items.original.map((item) => item.data);
 }
-function getScore(haystack, needle) {
-	if (!isSubsequence(haystack, needle)) return -1;
-	const lowerCaseHaystack = lowerCase(haystack);
-	const lowerCaseNeedle = lowerCase(needle);
-	const needleLength = lowerCaseNeedle.length;
+function getMatchEnd(haystack, needle, cursor) {
+	const haystackLength = haystack.length;
+	const needleLength = needle.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 += max([0, 5 - gap]);
+	for (let index = cursor; index < haystackLength; index += 1) if (haystack[index] === needle[needleIndex]) {
+		needleIndex += 1;
+		if (needleIndex === needleLength) return index;
+	}
+	return -1;
+}
+function getResult(state, exact, included, scored, options) {
+	const result = {
+		exact: [],
+		included: [],
+		similar: []
+	};
+	exact.sort(state.compare.item);
+	result.exact = exact.slice(0, options.limit).map((item) => item.data);
+	included.sort(state.compare.ranked);
+	result.included = included.slice(0, options.limit - result.exact.length).map((item) => item.data);
+	const remaining = options.limit - result.exact.length - result.included.length;
+	if (remaining === 0) return result;
+	const keys = Object.keys(scored).map(Number).sort((first, second) => second - first);
+	const keysLength = keys.length;
+	if (keysLength === 0) return result;
+	const maxScore = keys[0];
+	outer: for (let index = 0; index < keysLength; index += 1) {
+		const key = keys[index];
+		if (maxScore - key > options.tolerance) break;
+		const keyed = scored[key];
+		const keyedLength = keyed.length;
+		keyed.sort(state.compare.item);
+		for (let keyedIndex = 0; keyedIndex < keyedLength; keyedIndex += 1) {
+			result.similar.push(keyed[keyedIndex].data);
+			if (result.similar.length >= remaining) break outer;
+		}
+	}
+	return result;
+}
+function getScore(item, needle) {
+	const haystackLength = item.lowercase.length;
+	const needleLength = needle.length;
+	if (needleLength > haystackLength) return -1;
+	let best = -1;
+	let cursor = 0;
+	while (cursor < haystackLength) {
+		const end = getMatchEnd(item.lowercase, needle, cursor);
+		if (end === -1) break;
+		let index = end;
+		let needleIndex = needleLength - 1;
+		let next = -1;
+		let score = 0;
+		let start = end;
+		while (needleIndex >= 0) {
+			if (item.lowercase[index] === needle[needleIndex]) {
+				score += 1;
+				if (next !== -1) score += max([0, 5 - (next - index - 1)]);
+				if (isBoundary(item, index)) score += 2;
+				next = index;
+				start = index;
+				needleIndex -= 1;
 			}
-			previousMatchIndex = haystackIndex;
-			needleIndex += 1;
+			index -= 1;
 		}
-		if (needleIndex === needleLength) break;
+		if (start === 0) score += 1;
+		if (score > best) best = score;
+		cursor = start + 1;
 	}
-	score -= floor(lowerCaseHaystack.length / 3);
-	return max([0, score]);
+	if (best === -1) return -1;
+	return max([0, best - floor(haystackLength / 3)]);
+}
+function getStrings() {
+	return this[FUZZY_SYMBOL].items.original.map((item) => item.string.original);
 }
 function getTolerance(input, state) {
 	if (typeof input === "number" && !Number.isNaN(input)) return input < 0 ? 0 : floor(input);
 	return state?.tolerance ?? 5;
 }
+function isBoundary(string, index) {
+	if (index === 0 || FUZZY_BOUNDARY_SEPARATOR.test(string.lowercase[index - 1])) return true;
+	if (string.original.length !== string.lowercase.length) return false;
+	return string.original[index] !== string.lowercase[index] && string.original[index - 1] === string.lowercase[index - 1];
+}
 /**
 * Is the value a fuzzy searcher?
 *
@@ -118,74 +218,48 @@ function getTolerance(input, state) {
 function isFuzzy(value) {
 	return typeof value === "object" && value !== null && "$fuzzy" in value && value["$fuzzy"] === true;
 }
-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 search(input, option) {
 	const state = this[FUZZY_SYMBOL];
-	const options = option == null ? state : createFuzzyOptions(option, state);
-	const result = {
-		exact: [],
-		similar: []
-	};
+	const options = option == null ? state : createOptions(option, state);
 	const value = typeof input === "string" ? input.trim() : "";
+	const lowercaseValue = lowerCase(value);
 	if (value.length === 0) {
-		result.exact = state.items.slice(0, options.limit);
-		return result;
+		state.items.sorted ??= state.items.original.toSorted(state.compare.item);
+		return {
+			exact: state.items.sorted.slice(0, options.limit).map((item) => item.data),
+			included: [],
+			similar: []
+		};
 	}
-	let { length } = state.items;
 	const exact = [];
-	const similar = [];
+	const included = [];
 	const scored = {};
+	const { length } = state.items.original;
 	for (let index = 0; index < length; index += 1) {
-		const item = state.items[index];
-		const haystack = state.strings[index];
-		if (includes(haystack, value, true)) {
-			exact.push({
-				item,
-				haystack
-			});
+		const item = state.items.original[index];
+		const { string } = item;
+		if (string.lowercase === lowercaseValue) {
+			exact.push(item);
 			continue;
 		}
-		const score = getScore(haystack, value);
+		const position = string.lowercase.indexOf(lowercaseValue);
+		if (position > -1) {
+			included.push(createRanked(item, lowercaseValue, position));
+			continue;
+		}
+		const score = getScore(string, lowercaseValue);
 		if (score > -1) {
 			scored[score] ??= [];
-			scored[score].push({
-				item,
-				haystack
-			});
+			scored[score].push(item);
 		}
 	}
-	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(...createFuzzyItems(scored[key]));
-		}
-	}
-	result.exact = createFuzzyItems(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;
+	return getResult(state, exact, included, scored, options);
 }
-function setFuzzyItems(value) {
+function setItems(value) {
 	if (!Array.isArray(value)) throw new TypeError(FUZZY_MESSAGE_ARRAY);
-	const state = this[FUZZY_SYMBOL];
-	state.items = value.slice();
-	state.strings = value.map((item) => state.handler(item));
+	createItems(this[FUZZY_SYMBOL], value);
 }
+let defaultSorter;
 fuzzy.is = isFuzzy;
 fuzzy.match = fuzzyMatch;
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@oscarpalmer/atoms",
-	"version": "0.219.0",
+	"version": "0.220.0",
 	"description": "Atomic utilities for making your JavaScript better.",
 	"keywords": [
 		"array",