nhb-toolbox 4.10.74 → 4.10.76

package/dist/array/Finder.d.mts

@@ -0,0 +1,83 @@
+import { OwnKeys } from '../types/index.mjs';
+import { FindOptions } from './types.mjs';
+import '../object/types.mjs';
+
+type KeySelector<T> = Extract<OwnKeys<T>, string | number> | ((item: T) => string | number);
+/**
+ * The `Finder` class performs optimized searching on arrays.
+ * It supports binary search, fuzzy search, and smart caching with TTL.
+ */
+declare class Finder<T> {
+    #private;
+    /**
+     * * Creates a new `Finder` instance with a static array of items.
+     *
+     * @param data An array of items to initialize the search dataset.
+     * @param ttl Optional time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.
+     */
+    constructor(data: T[], ttl?: number);
+    /**
+     * * Creates a new `Finder` instance with a lazy-evaluated item provider.
+     *
+     * @param cb A function returning an array of items to initialize the search dataset.
+     * @param ttl Time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.
+     */
+    constructor(cb: () => T[], ttl?: number);
+    /**
+     * @instance Clears cache globally or for a specific key.
+     * @param key Optional key to clear only a specific cache entry.
+     */
+    clearCache(key?: string): void;
+    /**
+     * @instance Finds all items that match the provided matcher using optional caching or fuzzy logic.
+     * @param matcher The value to match against.
+     * @param keySelector Property key or selector function.
+     * @param options Optional settings for search behavior and source list.
+     */
+    findAll(matcher: string | number, keySelector: KeySelector<T>, options?: FindOptions<T>): T[];
+    /**
+     * @instance Finds first matching item that matches the provided matcher using optional caching or fuzzy logic.
+     * @param matcher The value to match.
+     * @param keySelector Property key or selector function.
+     * @param options Optional behavior flags and item source.
+     */
+    findOne(matcher: string | number, keySelector: KeySelector<T>, options?: FindOptions<T>): T | undefined;
+    /**
+     * @instance Asynchronous variant of `findAll` that accepts a promise-based data supplier.
+     * @param supplier Async function resolving the items list.
+     * @param matcher The value to match.
+     * @param keySelector Property key or selector function.
+     * @param options Optional settings for search behavior and cache.
+     */
+    findAllAsync(supplier: () => Promise<T[]>, matcher: string | number, keySelector: KeySelector<T>, options?: Omit<FindOptions<T>, 'items'>): Promise<T[]>;
+    /**
+     * @instance Asynchronous variant of `findOne`.
+     * @param supplier Async function resolving the items list.
+     * @param matcher The value to match.
+     * @param keySelector Property key or selector function.
+     * @param options Optional settings for behavior and cache.
+     */
+    findOneAsync(supplier: () => Promise<T[]>, matcher: string | number, keySelector: KeySelector<T>, options?: Omit<FindOptions<T>, 'items'>): Promise<T | undefined>;
+    /**
+     * @instance Performs a binary search on a sorted array using a custom key selector.
+     *
+     * @param sorted - The sorted array of items to search.
+     * @param matcher - The value to search for.
+     * @param keySelector - A function that extracts the comparable key from each item.
+     * @param caseInsensitive - Whether to compare string keys ignoring case.
+     * @returns The first matching item if found; otherwise, undefined.
+     */
+    binarySearch(sorted: T[], matcher: string | number, keySelector: (item: T) => string | number, caseInsensitive: boolean): T | undefined;
+    /**
+     * @instance Performs a fuzzy search on an array by matching characters in sequence.
+     *
+     * @param array - The array of items to search.
+     * @param matcher - The fuzzy search string to match against.
+     * @param keySelector - A function that extracts the key to search from each item.
+     * @param caseInsensitive - Whether to compare ignoring case for string values.
+     * @returns The first fuzzy-matching item if found; otherwise, undefined.
+     */
+    fuzzySearch(array: T[], matcher: string, keySelector: (item: T) => string | number, caseInsensitive: boolean): T | undefined;
+}
+
+export { Finder };

package/dist/{dts/array → array}/Finder.d.ts

@@ -1,11 +1,13 @@
-import type { OwnKeys } from '../types';
-import type { FindOptions } from './types';
+import { OwnKeys } from '../types/index.js';
+import { FindOptions } from './types.js';
+import '../object/types.js';
+
 type KeySelector<T> = Extract<OwnKeys<T>, string | number> | ((item: T) => string | number);
 /**
  * The `Finder` class performs optimized searching on arrays.
  * It supports binary search, fuzzy search, and smart caching with TTL.
  */
-export declare class Finder<T> {
+declare class Finder<T> {
     #private;
     /**
      * * Creates a new `Finder` instance with a static array of items.
@@ -77,5 +79,5 @@ export declare class Finder<T> {
      */
     fuzzySearch(array: T[], matcher: string, keySelector: (item: T) => string | number, caseInsensitive: boolean): T | undefined;
 }
-export {};
-//# sourceMappingURL=Finder.d.ts.map
+
+export { Finder };

package/dist/array/Finder.js

@@ -0,0 +1,300 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var Finder_exports = {};
+__export(Finder_exports, {
+  Finder: () => Finder
+});
+module.exports = __toCommonJS(Finder_exports);
+class Finder {
+  static #DEFAULT_TTL = 1e3 * 60 * 5;
+  #cachedResult = /* @__PURE__ */ new Map();
+  #sortedCache = /* @__PURE__ */ new Map();
+  #ttl;
+  #items;
+  /**
+   * * Creates a new `Finder` instance.
+   *
+   * @param data The initial array of items or a callback returning them.
+   * @param ttl Time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.
+   */
+  constructor(data, ttl = Finder.#DEFAULT_TTL) {
+    this.#ttl = ttl;
+    this.#items = typeof data === "function" ? data() : data;
+  }
+  /**
+   * @instance Clears cache globally or for a specific key.
+   * @param key Optional key to clear only a specific cache entry.
+   */
+  clearCache(key) {
+    if (key) {
+      this.#cachedResult.delete(key);
+    } else {
+      this.#cachedResult.clear();
+    }
+  }
+  /**
+   * @instance Finds all items that match the provided matcher using optional caching or fuzzy logic.
+   * @param matcher The value to match against.
+   * @param keySelector Property key or selector function.
+   * @param options Optional settings for search behavior and source list.
+   */
+  findAll(matcher, keySelector, options) {
+    const {
+      fuzzy = false,
+      needSorting = true,
+      cacheKey = "finder-cache",
+      forceBinary = false,
+      caseInsensitive = true,
+      data
+    } = options ?? {};
+    const source = typeof data === "function" ? data() : data ?? this.#items;
+    if (!source?.length) return [];
+    const rawGetKey = typeof keySelector === "function" ? keySelector : (item) => item[keySelector];
+    const getKey = Finder.#createMemoizedKeyGetter(rawGetKey);
+    const normalizedMatcher = caseInsensitive && typeof matcher === "string" ? matcher.toLowerCase() : matcher;
+    if (cacheKey) {
+      const entry = this.#cachedResult.get(cacheKey);
+      if (entry && Date.now() - entry.timestamp < this.#ttl) {
+        return entry.result;
+      } else {
+        this.#cachedResult.delete(cacheKey);
+      }
+    }
+    let results = [];
+    if (source.length < 100 && !forceBinary) {
+      results = source.filter((item) => {
+        const key = getKey(item);
+        const value = caseInsensitive && typeof key === "string" ? key.toLowerCase() : key;
+        return value === normalizedMatcher;
+      });
+    } else {
+      const sorted = needSorting ? this.#sortAndCache(source, getKey, cacheKey) : source;
+      const firstMatch = this.binarySearch(
+        sorted,
+        normalizedMatcher,
+        getKey,
+        caseInsensitive
+      );
+      if (firstMatch) {
+        const baseKey = getKey(firstMatch);
+        const base = caseInsensitive && typeof baseKey === "string" ? baseKey.toLowerCase() : baseKey;
+        results = sorted.filter((item) => {
+          const key = getKey(item);
+          const value = caseInsensitive && typeof key === "string" ? key.toLowerCase() : key;
+          return value === base;
+        });
+      }
+    }
+    if (!results.length && fuzzy && typeof normalizedMatcher === "string") {
+      results = source.filter((item) => {
+        const rawKey = getKey(item);
+        const key = caseInsensitive && typeof rawKey === "string" ? rawKey.toLowerCase() : String(rawKey);
+        return this.#match(key, normalizedMatcher);
+      });
+    }
+    if (cacheKey) {
+      this.#cachedResult.set(cacheKey, {
+        result: results,
+        timestamp: Date.now()
+      });
+    }
+    return results;
+  }
+  /**
+   * @instance Finds first matching item that matches the provided matcher using optional caching or fuzzy logic.
+   * @param matcher The value to match.
+   * @param keySelector Property key or selector function.
+   * @param options Optional behavior flags and item source.
+   */
+  findOne(matcher, keySelector, options) {
+    const {
+      fuzzy = false,
+      needSorting = true,
+      cacheKey = "finder-cache",
+      forceBinary = false,
+      caseInsensitive = true,
+      data
+    } = options ?? {};
+    const source = typeof data === "function" ? data() : data ?? this.#items;
+    if (!source?.length) return void 0;
+    const rawGetKey = typeof keySelector === "function" ? keySelector : (item) => item[keySelector];
+    const getKey = Finder.#createMemoizedKeyGetter(rawGetKey);
+    const normalizedMatcher = caseInsensitive && typeof matcher === "string" ? matcher.toLowerCase() : matcher;
+    if (cacheKey) {
+      const entry = this.#cachedResult.get(cacheKey);
+      if (entry && Date.now() - entry.timestamp < this.#ttl) {
+        return entry.result[0];
+      } else {
+        this.#cachedResult.delete(cacheKey);
+      }
+    }
+    let result;
+    if (source?.length < 100 && !forceBinary) {
+      result = source?.find((item) => {
+        const key = getKey(item);
+        const value = caseInsensitive && typeof key === "string" ? key.toLowerCase() : key;
+        return value === normalizedMatcher;
+      });
+    } else {
+      result = this.binarySearch(
+        needSorting ? this.#sortAndCache(source, getKey, cacheKey) : source,
+        normalizedMatcher,
+        getKey,
+        caseInsensitive
+      );
+    }
+    if (!result && fuzzy && typeof normalizedMatcher === "string") {
+      return this.fuzzySearch(
+        source,
+        normalizedMatcher,
+        getKey,
+        caseInsensitive
+      );
+    }
+    if (cacheKey && result) {
+      this.#cachedResult.set(cacheKey, {
+        result: [result],
+        timestamp: Date.now()
+      });
+    }
+    return result;
+  }
+  /**
+   * @instance Asynchronous variant of `findAll` that accepts a promise-based data supplier.
+   * @param supplier Async function resolving the items list.
+   * @param matcher The value to match.
+   * @param keySelector Property key or selector function.
+   * @param options Optional settings for search behavior and cache.
+   */
+  async findAllAsync(supplier, matcher, keySelector, options) {
+    const items = await supplier();
+    return this.findAll(matcher, keySelector, { ...options, data: items });
+  }
+  /**
+   * @instance Asynchronous variant of `findOne`.
+   * @param supplier Async function resolving the items list.
+   * @param matcher The value to match.
+   * @param keySelector Property key or selector function.
+   * @param options Optional settings for behavior and cache.
+   */
+  async findOneAsync(supplier, matcher, keySelector, options) {
+    const items = await supplier();
+    return this.findOne(matcher, keySelector, { ...options, data: items });
+  }
+  /**
+   * @instance Performs a binary search on a sorted array using a custom key selector.
+   *
+   * @param sorted - The sorted array of items to search.
+   * @param matcher - The value to search for.
+   * @param keySelector - A function that extracts the comparable key from each item.
+   * @param caseInsensitive - Whether to compare string keys ignoring case.
+   * @returns The first matching item if found; otherwise, undefined.
+   */
+  binarySearch(sorted, matcher, keySelector, caseInsensitive) {
+    let min = 0, max = sorted?.length - 1;
+    while (min <= max) {
+      const mid = Math.floor((min + max) / 2);
+      const midKey = keySelector(sorted[mid]);
+      const key = caseInsensitive && typeof midKey === "string" ? midKey.toLowerCase() : midKey;
+      if (key === matcher) return sorted[mid];
+      if (key < matcher) min = mid + 1;
+      else max = mid - 1;
+    }
+    return void 0;
+  }
+  /**
+   * @instance Performs a fuzzy search on an array by matching characters in sequence.
+   *
+   * @param array - The array of items to search.
+   * @param matcher - The fuzzy search string to match against.
+   * @param keySelector - A function that extracts the key to search from each item.
+   * @param caseInsensitive - Whether to compare ignoring case for string values.
+   * @returns The first fuzzy-matching item if found; otherwise, undefined.
+   */
+  fuzzySearch(array, matcher, keySelector, caseInsensitive) {
+    for (const item of array) {
+      const rawKey = keySelector(item);
+      const key = caseInsensitive && typeof rawKey === "string" ? rawKey.toLowerCase() : String(rawKey);
+      if (this.#match(key, matcher)) return item;
+    }
+    return void 0;
+  }
+  /**
+   * @private Checks if the characters in the target string appear in order within the source string.
+   * @param source Source string to search within.
+   * @param target Target string to match against the source string.
+   * @returns True if the target string is a fuzzy match within the source string; otherwise, false.
+   */
+  #match(source, target) {
+    let i = 0;
+    for (const char of target) {
+      i = source?.indexOf(char, i);
+      if (i === -1) return false;
+      i++;
+    }
+    return true;
+  }
+  /**
+   * @private Sorts an array and caches the result for a specified time-to-live (TTL).
+   * @param data Data to sort and cache.
+   * @param getKey Key extraction function.
+   * @param cacheKey Optional cache key for storing the result.
+   * @returns
+   */
+  #sortAndCache(data, getKey, cacheKey) {
+    if (cacheKey) {
+      const entry = this.#sortedCache.get(cacheKey);
+      if (entry && Date.now() - entry.timestamp < this.#ttl) {
+        return entry.result;
+      } else {
+        this.#sortedCache.delete(cacheKey);
+      }
+    }
+    const sorted = [...data].sort((a, b) => {
+      const keyA = getKey(a);
+      const keyB = getKey(b);
+      return keyA < keyB ? -1 : keyA > keyB ? 1 : 0;
+    });
+    if (cacheKey) {
+      this.#sortedCache.set(cacheKey, {
+        result: sorted,
+        timestamp: Date.now()
+      });
+    }
+    return sorted;
+  }
+  /**
+   * @static @private Creates a memoized version of a key extractor.
+   * @param getKey Original key extraction function
+   */
+  static #createMemoizedKeyGetter(getKey) {
+    const cache = /* @__PURE__ */ new Map();
+    return (item) => {
+      if (cache.has(item)) return cache.get(item);
+      const key = getKey(item);
+      cache.set(item, key);
+      return key;
+    };
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Finder
+});
+//# sourceMappingURL=Finder.js.map

package/dist/array/Finder.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/array/Finder.ts"],"sourcesContent":["import type { OwnKeys } from '../types';\nimport type { FindOptions } from './types';\n\ntype KeySelector<T> =\n\t| Extract<OwnKeys<T>, string | number>\n\t| ((item: T) => string | number);\n\ntype CacheEntry<T> = { result: T[]; timestamp: number };\n\n/**\n * The `Finder` class performs optimized searching on arrays.\n * It supports binary search, fuzzy search, and smart caching with TTL.\n */\nexport class Finder<T> {\n\tstatic readonly #DEFAULT_TTL = 1000 * 60 * 5;\n\n\treadonly #cachedResult: Map<string, CacheEntry<T>> = new Map();\n\treadonly #sortedCache: Map<string, CacheEntry<T>> = new Map();\n\treadonly #ttl: number;\n\treadonly #items: T[];\n\n\t/**\n\t * * Creates a new `Finder` instance with a static array of items.\n\t *\n\t * @param data An array of items to initialize the search dataset.\n\t * @param ttl Optional time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.\n\t */\n\tconstructor(data: T[], ttl?: number);\n\n\t/**\n\t * * Creates a new `Finder` instance with a lazy-evaluated item provider.\n\t *\n\t * @param cb A function returning an array of items to initialize the search dataset.\n\t * @param ttl Time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.\n\t */\n\tconstructor(cb: () => T[], ttl?: number);\n\n\t/**\n\t * * Creates a new `Finder` instance.\n\t *\n\t * @param data The initial array of items or a callback returning them.\n\t * @param ttl Time-to-live (in milliseconds) for cached search results. Defaults to {@link Finder.#DEFAULT_TTL 5 Minutes}.\n\t */\n\tconstructor(data: T[] | (() => T[]), ttl: number = Finder.#DEFAULT_TTL) {\n\t\tthis.#ttl = ttl;\n\t\tthis.#items = typeof data === 'function' ? data() : data;\n\t}\n\n\t/**\n\t * @instance Clears cache globally or for a specific key.\n\t * @param key Optional key to clear only a specific cache entry.\n\t */\n\tclearCache(key?: string): void {\n\t\tif (key) {\n\t\t\tthis.#cachedResult.delete(key);\n\t\t} else {\n\t\t\tthis.#cachedResult.clear();\n\t\t}\n\t}\n\n\t/**\n\t * @instance Finds all items that match the provided matcher using optional caching or fuzzy logic.\n\t * @param matcher The value to match against.\n\t * @param keySelector Property key or selector function.\n\t * @param options Optional settings for search behavior and source list.\n\t */\n\tfindAll(\n\t\tmatcher: string | number,\n\t\tkeySelector: KeySelector<T>,\n\t\toptions?: FindOptions<T>,\n\t): T[] {\n\t\tconst {\n\t\t\tfuzzy = false,\n\t\t\tneedSorting = true,\n\t\t\tcacheKey = 'finder-cache',\n\t\t\tforceBinary = false,\n\t\t\tcaseInsensitive = true,\n\t\t\tdata,\n\t\t} = options ?? {};\n\n\t\tconst source =\n\t\t\ttypeof data === 'function' ? data() : (data ?? this.#items);\n\n\t\tif (!source?.length) return [];\n\n\t\tconst rawGetKey =\n\t\t\ttypeof keySelector === 'function' ? keySelector : (\n\t\t\t\t(item: T) => item[keySelector] as string | number\n\t\t\t);\n\n\t\tconst getKey = Finder.#createMemoizedKeyGetter(rawGetKey);\n\n\t\tconst normalizedMatcher =\n\t\t\tcaseInsensitive && typeof matcher === 'string' ?\n\t\t\t\tmatcher.toLowerCase()\n\t\t\t:\tmatcher;\n\n\t\tif (cacheKey) {\n\t\t\tconst entry = this.#cachedResult.get(cacheKey);\n\n\t\t\tif (entry && Date.now() - entry.timestamp < this.#ttl) {\n\t\t\t\treturn entry.result;\n\t\t\t} else {\n\t\t\t\tthis.#cachedResult.delete(cacheKey);\n\t\t\t}\n\t\t}\n\n\t\tlet results: T[] = [];\n\n\t\tif (source.length < 100 && !forceBinary) {\n\t\t\tresults = source.filter((item) => {\n\t\t\t\tconst key = getKey(item);\n\t\t\t\tconst value =\n\t\t\t\t\tcaseInsensitive && typeof key === 'string' ?\n\t\t\t\t\t\tkey.toLowerCase()\n\t\t\t\t\t:\tkey;\n\t\t\t\treturn value === normalizedMatcher;\n\t\t\t});\n\t\t} else {\n\t\t\tconst sorted =\n\t\t\t\tneedSorting ?\n\t\t\t\t\tthis.#sortAndCache(source, getKey, cacheKey)\n\t\t\t\t:\tsource;\n\n\t\t\tconst firstMatch = this.binarySearch(\n\t\t\t\tsorted,\n\t\t\t\tnormalizedMatcher,\n\t\t\t\tgetKey,\n\t\t\t\tcaseInsensitive,\n\t\t\t);\n\n\t\t\tif (firstMatch) {\n\t\t\t\tconst baseKey = getKey(firstMatch);\n\n\t\t\t\tconst base =\n\t\t\t\t\tcaseInsensitive && typeof baseKey === 'string' ?\n\t\t\t\t\t\tbaseKey.toLowerCase()\n\t\t\t\t\t:\tbaseKey;\n\n\t\t\t\tresults = sorted.filter((item) => {\n\t\t\t\t\tconst key = getKey(item);\n\n\t\t\t\t\tconst value =\n\t\t\t\t\t\tcaseInsensitive && typeof key === 'string' ?\n\t\t\t\t\t\t\tkey.toLowerCase()\n\t\t\t\t\t\t:\tkey;\n\n\t\t\t\t\treturn value === base;\n\t\t\t\t});\n\t\t\t}\n\t\t}\n\n\t\tif (!results.length && fuzzy && typeof normalizedMatcher === 'string') {\n\t\t\tresults = source.filter((item) => {\n\t\t\t\tconst rawKey = getKey(item);\n\n\t\t\t\tconst key =\n\t\t\t\t\tcaseInsensitive && typeof rawKey === 'string' ?\n\t\t\t\t\t\trawKey.toLowerCase()\n\t\t\t\t\t:\tString(rawKey);\n\n\t\t\t\treturn this.#match(key, normalizedMatcher);\n\t\t\t});\n\t\t}\n\n\t\tif (cacheKey) {\n\t\t\tthis.#cachedResult.set(cacheKey, {\n\t\t\t\tresult: results,\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t});\n\t\t}\n\n\t\treturn results;\n\t}\n\n\t/**\n\t * @instance Finds first matching item that matches the provided matcher using optional caching or fuzzy logic.\n\t * @param matcher The value to match.\n\t * @param keySelector Property key or selector function.\n\t * @param options Optional behavior flags and item source.\n\t */\n\tfindOne(\n\t\tmatcher: string | number,\n\t\tkeySelector: KeySelector<T>,\n\t\toptions?: FindOptions<T>,\n\t): T | undefined {\n\t\tconst {\n\t\t\tfuzzy = false,\n\t\t\tneedSorting = true,\n\t\t\tcacheKey = 'finder-cache',\n\t\t\tforceBinary = false,\n\t\t\tcaseInsensitive = true,\n\t\t\tdata,\n\t\t} = options ?? {};\n\n\t\tconst source =\n\t\t\ttypeof data === 'function' ? data() : (data ?? this.#items);\n\n\t\tif (!source?.length) return undefined;\n\n\t\tconst rawGetKey =\n\t\t\ttypeof keySelector === 'function' ? keySelector : (\n\t\t\t\t(item: T) => item[keySelector] as string | number\n\t\t\t);\n\n\t\tconst getKey = Finder.#createMemoizedKeyGetter(rawGetKey);\n\n\t\tconst normalizedMatcher =\n\t\t\tcaseInsensitive && typeof matcher === 'string' ?\n\t\t\t\tmatcher.toLowerCase()\n\t\t\t:\tmatcher;\n\n\t\tif (cacheKey) {\n\t\t\tconst entry = this.#cachedResult.get(cacheKey);\n\n\t\t\tif (entry && Date.now() - entry.timestamp < this.#ttl) {\n\t\t\t\treturn entry.result[0];\n\t\t\t} else {\n\t\t\t\tthis.#cachedResult.delete(cacheKey);\n\t\t\t}\n\t\t}\n\n\t\tlet result: T | undefined;\n\n\t\tif (source?.length < 100 && !forceBinary) {\n\t\t\tresult = source?.find((item) => {\n\t\t\t\tconst key = getKey(item);\n\t\t\t\tconst value =\n\t\t\t\t\tcaseInsensitive && typeof key === 'string' ?\n\t\t\t\t\t\tkey.toLowerCase()\n\t\t\t\t\t:\tkey;\n\t\t\t\treturn value === normalizedMatcher;\n\t\t\t});\n\t\t} else {\n\t\t\tresult = this.binarySearch(\n\t\t\t\tneedSorting ?\n\t\t\t\t\tthis.#sortAndCache(source, getKey, cacheKey)\n\t\t\t\t:\tsource,\n\t\t\t\tnormalizedMatcher,\n\t\t\t\tgetKey,\n\t\t\t\tcaseInsensitive,\n\t\t\t);\n\t\t}\n\n\t\tif (!result && fuzzy && typeof normalizedMatcher === 'string') {\n\t\t\treturn this.fuzzySearch(\n\t\t\t\tsource,\n\t\t\t\tnormalizedMatcher,\n\t\t\t\tgetKey,\n\t\t\t\tcaseInsensitive,\n\t\t\t);\n\t\t}\n\n\t\tif (cacheKey && result) {\n\t\t\tthis.#cachedResult.set(cacheKey, {\n\t\t\t\tresult: [result],\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t});\n\t\t}\n\n\t\treturn result;\n\t}\n\n\t/**\n\t * @instance Asynchronous variant of `findAll` that accepts a promise-based data supplier.\n\t * @param supplier Async function resolving the items list.\n\t * @param matcher The value to match.\n\t * @param keySelector Property key or selector function.\n\t * @param options Optional settings for search behavior and cache.\n\t */\n\tasync findAllAsync(\n\t\tsupplier: () => Promise<T[]>,\n\t\tmatcher: string | number,\n\t\tkeySelector: KeySelector<T>,\n\t\toptions?: Omit<FindOptions<T>, 'items'>,\n\t): Promise<T[]> {\n\t\tconst items = await supplier();\n\n\t\treturn this.findAll(matcher, keySelector, { ...options, data: items });\n\t}\n\n\t/**\n\t * @instance Asynchronous variant of `findOne`.\n\t * @param supplier Async function resolving the items list.\n\t * @param matcher The value to match.\n\t * @param keySelector Property key or selector function.\n\t * @param options Optional settings for behavior and cache.\n\t */\n\tasync findOneAsync(\n\t\tsupplier: () => Promise<T[]>,\n\t\tmatcher: string | number,\n\t\tkeySelector: KeySelector<T>,\n\t\toptions?: Omit<FindOptions<T>, 'items'>,\n\t): Promise<T | undefined> {\n\t\tconst items = await supplier();\n\n\t\treturn this.findOne(matcher, keySelector, { ...options, data: items });\n\t}\n\n\t/**\n\t * @instance Performs a binary search on a sorted array using a custom key selector.\n\t *\n\t * @param sorted - The sorted array of items to search.\n\t * @param matcher - The value to search for.\n\t * @param keySelector - A function that extracts the comparable key from each item.\n\t * @param caseInsensitive - Whether to compare string keys ignoring case.\n\t * @returns The first matching item if found; otherwise, undefined.\n\t */\n\tbinarySearch(\n\t\tsorted: T[],\n\t\tmatcher: string | number,\n\t\tkeySelector: (item: T) => string | number,\n\t\tcaseInsensitive: boolean,\n\t): T | undefined {\n\t\tlet min = 0,\n\t\t\tmax = sorted?.length - 1;\n\n\t\twhile (min <= max) {\n\t\t\tconst mid = Math.floor((min + max) / 2);\n\t\t\tconst midKey = keySelector(sorted[mid]);\n\t\t\tconst key =\n\t\t\t\tcaseInsensitive && typeof midKey === 'string' ?\n\t\t\t\t\tmidKey.toLowerCase()\n\t\t\t\t:\tmidKey;\n\n\t\t\tif (key === matcher) return sorted[mid];\n\t\t\tif (key < matcher) min = mid + 1;\n\t\t\telse max = mid - 1;\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * @instance Performs a fuzzy search on an array by matching characters in sequence.\n\t *\n\t * @param array - The array of items to search.\n\t * @param matcher - The fuzzy search string to match against.\n\t * @param keySelector - A function that extracts the key to search from each item.\n\t * @param caseInsensitive - Whether to compare ignoring case for string values.\n\t * @returns The first fuzzy-matching item if found; otherwise, undefined.\n\t */\n\tfuzzySearch(\n\t\tarray: T[],\n\t\tmatcher: string,\n\t\tkeySelector: (item: T) => string | number,\n\t\tcaseInsensitive: boolean,\n\t): T | undefined {\n\t\tfor (const item of array) {\n\t\t\tconst rawKey = keySelector(item);\n\t\t\tconst key =\n\t\t\t\tcaseInsensitive && typeof rawKey === 'string' ?\n\t\t\t\t\trawKey.toLowerCase()\n\t\t\t\t:\tString(rawKey);\n\t\t\tif (this.#match(key, matcher)) return item;\n\t\t}\n\n\t\treturn undefined;\n\t}\n\n\t/**\n\t * @private Checks if the characters in the target string appear in order within the source string.\n\t * @param source Source string to search within.\n\t * @param target Target string to match against the source string.\n\t * @returns True if the target string is a fuzzy match within the source string; otherwise, false.\n\t */\n\t#match(source: string, target: string): boolean {\n\t\tlet i = 0;\n\n\t\tfor (const char of target) {\n\t\t\ti = source?.indexOf(char, i);\n\t\t\tif (i === -1) return false;\n\t\t\ti++;\n\t\t}\n\n\t\treturn true;\n\t}\n\n\t/**\n\t * @private Sorts an array and caches the result for a specified time-to-live (TTL).\n\t * @param data Data to sort and cache.\n\t * @param getKey Key extraction function.\n\t * @param cacheKey Optional cache key for storing the result.\n\t * @returns\n\t */\n\t#sortAndCache(\n\t\tdata: T[],\n\t\tgetKey: (item: T) => string | number,\n\t\tcacheKey?: string,\n\t) {\n\t\tif (cacheKey) {\n\t\t\tconst entry = this.#sortedCache.get(cacheKey);\n\n\t\t\tif (entry && Date.now() - entry.timestamp < this.#ttl) {\n\t\t\t\treturn entry.result;\n\t\t\t} else {\n\t\t\t\tthis.#sortedCache.delete(cacheKey);\n\t\t\t}\n\t\t}\n\n\t\tconst sorted = [...data].sort((a, b) => {\n\t\t\tconst keyA = getKey(a);\n\t\t\tconst keyB = getKey(b);\n\t\t\treturn (\n\t\t\t\tkeyA < keyB ? -1\n\t\t\t\t: keyA > keyB ? 1\n\t\t\t\t: 0\n\t\t\t);\n\t\t});\n\n\t\tif (cacheKey) {\n\t\t\tthis.#sortedCache.set(cacheKey, {\n\t\t\t\tresult: sorted,\n\t\t\t\ttimestamp: Date.now(),\n\t\t\t});\n\t\t}\n\n\t\treturn sorted;\n\t}\n\n\t/**\n\t * @static @private Creates a memoized version of a key extractor.\n\t * @param getKey Original key extraction function\n\t */\n\tstatic #createMemoizedKeyGetter<T>(\n\t\tgetKey: (item: T) => string | number,\n\t): (item: T) => string | number {\n\t\tconst cache = new Map<T, string | number>();\n\n\t\treturn (item: T): string | number => {\n\t\t\tif (cache.has(item)) return cache.get(item)!;\n\t\t\tconst key = getKey(item);\n\t\t\tcache.set(item, key);\n\t\t\treturn key;\n\t\t};\n\t}\n}\n"],"mappings":"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","names":[]}