@oscarpalmer/atoms 0.192.0 → 0.193.1

package/src/string/case.ts

@@ -1,236 +0,0 @@
-import {memoize, type Memoized} from '../function/memoize';
-import {join, words} from '../internal/string';
-
-// #region Types
-
-type Case = 'camel' | 'kebab' | 'pascal' | 'snake';
-
-type Options = {
-	capitalizeAny: boolean;
-	capitalizeFirst: boolean;
-	type: Case;
-};
-
-// #endregion
-
-// #region Functions
-
-/**
- * Convert a string to camel case _(thisIsCamelCase)_
- *
- * @param value String to convert
- * @returns Camel-cased string
- */
-export function camelCase(value: string): string {
-	return toCase(CASE_CAMEL, value, true, false);
-}
-
-/**
- * Capitalize the first letter of a string _(and lowercase the rest)_
- *
- * @param value String to capitalize
- * @returns Capitalized string
- */
-export function capitalize(value: string): string {
-	if (typeof value !== 'string' || value.length === 0) {
-		return '';
-	}
-
-	memoizedCapitalize ??= memoize(v =>
-		v.length === 1
-			? v.toLocaleUpperCase()
-			: `${v.charAt(0).toLocaleUpperCase()}${v.slice(1).toLocaleLowerCase()}`,
-	);
-
-	return memoizedCapitalize.run(value);
-}
-
-/**
- * Convert a string to kebab case _(this-is-kebab-case)_
- *
- * @param value String to convert
- * @returns Kebab-cased string
- */
-export function kebabCase(value: string): string {
-	return toCase(CASE_KEBAB, value, false, false);
-}
-
-/**
- * Convert a string to lower case
- *
- * @param value String to convert
- * @returns Lower-cased string
- */
-export function lowerCase(value: string): string {
-	if (typeof value !== 'string') {
-		return '';
-	}
-
-	memoizedLowerCase ??= memoize(v => v.toLocaleLowerCase());
-
-	return memoizedLowerCase.run(value);
-}
-
-/**
- * Convert a string to pascal case _(ThisIsPascalCase)_
- *
- * @param value String to convert
- * @returns Pascal-cased string
- */
-export function pascalCase(value: string): string {
-	return toCase(CASE_PASCAL, value, true, true);
-}
-
-/**
- * Convert a string to snake case _(this_is_snake_case)_
- *
- * @param value String to convert
- * @returns Snake-cased string
- */
-export function snakeCase(value: string): string {
-	return toCase(CASE_SNAKE, value, false, false);
-}
-
-/**
- * Convert a string to title case _(Capitalizing Every Word)_
- *
- * @param value String to convert
- * @returns Title-cased string
- */
-export function titleCase(value: string): string {
-	if (typeof value !== 'string' || value.length === 0) {
-		return '';
-	}
-
-	memoizedTitleCase ??= memoize(v =>
-		v.length < 2 ? capitalize(v) : join(words(v).map(capitalize), ' '),
-	);
-
-	return memoizedTitleCase.run(value);
-}
-
-function toCase(
-	type: Case,
-	value: string,
-	capitalizeAny: boolean,
-	capitalizeFirst: boolean,
-): string {
-	caseMemoizers[type] ??= memoize(toCaseCallback.bind({type, capitalizeAny, capitalizeFirst}));
-
-	return caseMemoizers[type].run(value);
-}
-
-function toCaseCallback(this: Options, value: string): string {
-	if (typeof value !== 'string') {
-		return '';
-	}
-
-	if (value.length < 1) {
-		return value;
-	}
-
-	const {capitalizeAny, capitalizeFirst, type} = this;
-
-	const parts = words(value);
-	const partsLength = parts.length;
-
-	const cased: string[] = [];
-
-	for (let partIndex = 0; partIndex < partsLength; partIndex += 1) {
-		const part = parts[partIndex];
-
-		const acronymParts = part.replace(EXPRESSION_ACRONYM, (full, one, two, three) =>
-			three === S ? full : `${one}-${two}${three}`,
-		);
-
-		const camelCaseParts = acronymParts.replace(EXPRESSION_CAMEL_CASE, REPLACEMENT_CAMEL_CASE);
-
-		const items = camelCaseParts.split('-');
-		const itemsLength = items.length;
-
-		const partResult: string[] = [];
-
-		let itemCount = 0;
-
-		for (let itemIndex = 0; itemIndex < itemsLength; itemIndex += 1) {
-			const item = items[itemIndex];
-
-			if (item.length === 0) {
-				continue;
-			}
-
-			if (!capitalizeAny || (itemCount === 0 && partIndex === 0 && !capitalizeFirst)) {
-				partResult.push(item.toLocaleLowerCase());
-			} else {
-				partResult.push(capitalize(item));
-			}
-
-			itemCount += 1;
-		}
-
-		cased.push(join(partResult, delimiters[type]));
-	}
-
-	return join(cased, delimiters[type]);
-}
-
-/**
- * Convert a string to upper case
- *
- * @param value String to convert
- * @returns Upper-cased string
- */
-export function upperCase(value: string): string {
-	if (typeof value !== 'string' || value.length === 0) {
-		return '';
-	}
-
-	memoizedUpperCase ??= memoize(v => v.toLocaleUpperCase());
-
-	return memoizedUpperCase.run(value);
-}
-
-// #endregion
-
-// #region Variables
-
-const CASE_CAMEL: Case = 'camel';
-
-const CASE_KEBAB: Case = 'kebab';
-
-const CASE_PASCAL: Case = 'pascal';
-
-const CASE_SNAKE: Case = 'snake';
-
-const DELIMTER_EMPTY = '';
-
-const DELIMITER_HYPHEN = '-';
-
-const DELIMITER_UNDERSCORE = '_';
-
-const EXPRESSION_CAMEL_CASE = /(\p{Ll})(\p{Lu})/gu;
-
-const EXPRESSION_ACRONYM = /(\p{Lu}*)(\p{Lu})(\p{Ll}+)/gu;
-
-const REPLACEMENT_CAMEL_CASE = '$1-$2';
-
-const S = 's';
-
-const caseMemoizers: Partial<Record<string, Memoized<typeof toCaseCallback>>> = {};
-
-const delimiters: Record<Case, string> = {
-	[CASE_CAMEL]: DELIMTER_EMPTY,
-	[CASE_KEBAB]: DELIMITER_HYPHEN,
-	[CASE_PASCAL]: DELIMTER_EMPTY,
-	[CASE_SNAKE]: DELIMITER_UNDERSCORE,
-};
-
-let memoizedCapitalize: Memoized<(value: string) => string>;
-
-let memoizedLowerCase: Memoized<(value: string) => string>;
-
-let memoizedTitleCase: Memoized<(value: string) => string>;
-
-let memoizedUpperCase: Memoized<(value: string) => string>;
-
-// #endregion

package/src/string/fuzzy.ts

@@ -1,444 +0,0 @@
-import {isPlainObject} from '../internal/is';
-import {getString} from '../internal/string';
-import type {PlainObject, RequiredKeys} from '../models';
-import {lowerCase} from './case';
-import {includes} from './match';
-
-// #region Types
-
-/**
- * Fuzzy searcher for an array of items
- */
-export type Fuzzy<Item> = {
-	/**
-	 * Get items currently being searched through
-	 *
-	 * @returns Original items
-	 */
-	get items(): Item[];
-
-	/**
-	 * Set new items to search through
-	 *
-	 * @param items New items to search through
-	 */
-	set items(items: Item[]);
-
-	/**
-	 * Get strings currently being searched through _(the stringified version of `items`)_
-	 *
-	 * @returns Stringified items
-	 */
-	get strings(): string[];
-
-	/**
-	 * 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>;
-};
-
-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 getFuzzyOptions<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;
-	}
-
-	options.tolerance = getTolerance(options.tolerance, state);
-
-	return options as RequiredKeys<FuzzyOptions, 'tolerance'>;
-}
-
-function getFuzzyState<Item>(items: Item[], input: unknown): FuzzyState<Item> {
-	const handler = getHandler(input);
-	const options = getFuzzyOptions(input);
-
-	return {
-		handler,
-		items: items.slice(),
-		limit: options.limit,
-		strings: items.map(handler),
-		tolerance: options.tolerance,
-	};
-}
-
-function getTolerance<Item>(input: unknown, state?: FuzzyState<Item>): number {
-	if (typeof input === 'number' && !Number.isNaN(input)) {
-		return input < 0 ? 0 : Math.floor(input);
-	}
-
-	return state?.tolerance ?? PROXIMITY_THRESHOLD;
-}
-
-/**
- * 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);
-	}
-
-	const state = getFuzzyState(items, configuration);
-
-	const instance = {
-		search: (value: string, options?: number | FuzzyOptions) =>
-			search(
-				state.items,
-				state.strings,
-				value,
-				options == null ? state : getFuzzyOptions(options, state),
-			),
-	};
-
-	Object.defineProperties(instance, {
-		items: {
-			get: () => state.items.slice(),
-			set: (items: unknown[]) => {
-				if (!Array.isArray(items)) {
-					throw new TypeError(MESSAGE_ARRAY);
-				}
-
-				state.items = items.slice();
-				state.strings = items.map(state.handler);
-			},
-		},
-		strings: {
-			get: () => state.strings.slice(),
-		},
-	});
-
-	return Object.freeze(instance) as Fuzzy<unknown>;
-}
-
-fuzzy.match = fuzzyMatch;
-
-/**
- * Does the needle match the haystack in a fuzzy way?
- *
- * @param haystack Haystack to search through
- * @param needle Needle to search for
- * @returns `true` if the needle matches the haystack in a fuzzy way, otherwise `false`
- */
-export function fuzzyMatch(haystack: string, needle: string): boolean {
-	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;
-}
-
-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