@superutils/core 1.0.5 → 1.0.6

package/README.md

@@ -222,7 +222,7 @@ search(data, { query: { age: 28, name: 've' } })
 //     [4, { age: 28, name: 'Dave' }],
 // ])
 
-// Fuzzy search accross all properties
+// Search across all properties
 search(data, { query: 'li' })
 search(data, { query: /li/i }) // Using regular expression
 // Result:
@@ -255,7 +255,7 @@ search(data, {
 		age: /(2[5-9])|(3[0-5])/, // match ages 25-35
 		name: /ali|ob|ve/i,
 	},
-	// transform the property values (or item itself when in fuzzy search mode)
+	// transform the property values (or item itself when searching all properties in global search mode using `query: string | RegExp`)
 	transform: (item, value, property) => {
 		// exclude items by returning undefined or emptry string
 		if (item.age < 18) return ''

package/dist/index.d.ts

@@ -966,7 +966,7 @@ type SortOptions = {
     undefinedFirst?: boolean;
 };
 /** Search criteria for searcheing iterables */
-type SearchOptions<K, V, AsMap extends boolean = false> = {
+type SearchOptions<K, V, MatchExact extends boolean = false, AsMap extends boolean = false> = {
     /** Whethere to return the result as a map (`true`) or array (`false`). Default: `true` */
     asMap?: AsMap;
     /** case-insensitive search for strings. Default: `false` */
@@ -974,21 +974,33 @@ type SearchOptions<K, V, AsMap extends boolean = false> = {
     /** limit number of results. Default: `Infinity` */
     limit?: number;
     /** partial match for values. Default: `false` */
-    matchExact?: boolean;
+    matchExact?: MatchExact;
     /** match all supplied key-value pairs. Default: `false` */
     matchAll?: boolean;
     /** key-value pairs */
-    query: Record<string, unknown> | string | RegExp;
+    query: Record<PropertyKey, unknown> | RegExp | string;
+    /** If `true`, the results are sorted by relevance (match index). Default: `false` */
+    ranked?: boolean;
     /** Map to store results in. Default: `new Map()` */
     result?: Map<K, V>;
-    /** Callback to convert item/item-property to string */
-    transform?: (
+    /**
+     * Boolean or Callback to prepare item or individual property for search by converting to string.
+     *
+     * - `true`: value will be stringified
+     * - `false`: value will not be stringified when `matchExact = true`
+     * - `function`: transformed value will be used to search
+     *
+     * Returning "empty" (`undefined | null | [] | '' | ...`) value will ignore the item/property.
+     *
+     * Default: `true`
+     */
+    transform?: boolean | ((
     /** List item */
     item: V, 
-    /** Item property value or `undefined` for fuzzy search. */
+    /** Item property value or `undefined` for global search across all properties. */
     value?: V[keyof V], 
-    /** Item property key provided by query or `undefined` for fuzzy search. */
-    key?: keyof V) => string | undefined;
+    /** Item property key provided by query or `undefined` for global search across all properties. */
+    key?: keyof V) => MatchExact extends true ? unknown : string | undefined);
 };
 
 /**
@@ -1085,8 +1097,8 @@ declare const getValues: <K, V>(data: IterableList<K, V>) => V[];
 declare const reverse: <K, V, T extends IterableList<K, V>>(data: T, reverse?: boolean, newInstance?: boolean) => V[] | [K, V][] | Map<K, V> | Set<V> | (T & Record<"clear", unknown>);
 
 /**
- * A versatile utility for searching through an iterable list (e.g., Array, Map, Set) of objects.
- * It supports both a simple "fuzzy" search with a string query across all properties and a
+ * A versatile utility for searching through an iterable list (Array, Map, or Set) of objects.
+ * It supports both a global search (using a string or RegExp) across all properties of an item, and a
  * detailed, field-specific search using a query object.
  *
  * @param data The list of objects to search within. Compatible types include:
@@ -1097,6 +1109,8 @@ declare const reverse: <K, V, T extends IterableList<K, V>>(data: T, reverse?: b
  * - `HTMLCollection` (in DOM environments): should accompany `options.transform()`
  * @param options The search criteria.
  * @param options.query The search query. Can be a string to search all fields, or an object for field-specific
+ * @param options.ranked (optional) If `true`, the results are sorted by relevance (match index). Default: `false`.
+ *
  * searches (e.g., `{ name: 'John', city: 'New York' }`).
  * @param options.asMap (optional) If `true`, returns a `Map`. If `false`, returns an `Array`. Default: `true`.
  * @param options.ignoreCase (optional) If `true`, performs a case-insensitive search for strings. Default: `true`.
@@ -1131,12 +1145,16 @@ declare const reverse: <K, V, T extends IterableList<K, V>>(data: T, reverse?: b
  * ```
  */
 declare const search: {
-    <K, V, AsMap extends boolean = true, Result = AsMap extends true ? Map<K, V> : V[]>(data: IterableList<K, V>, options: SearchOptions<K, V, AsMap>): Result;
-    defaultOptions: Pick<Required<SearchOptions<unknown, unknown, true>>, "matchAll" | "limit" | "asMap" | "ignoreCase" | "matchExact">;
+    <K, V, MatchExact extends boolean = false, AsMap extends boolean = true, Result = AsMap extends true ? Map<K, V> : V[]>(data: IterableList<K, V>, options: SearchOptions<K, V, MatchExact, AsMap>): Result;
+    defaultOptions: Pick<Required<SearchOptions<unknown, unknown, false, true>>, "matchAll" | "limit" | "asMap" | "ignoreCase" | "ranked" | "transform">;
 };
-/** Utility for use with {@link search} function */
-declare function matchItemOrProp<K, V>(// extends Record<string, unknown>
-{ query, ignoreCase, matchExact, transform, }: Pick<SearchOptions<K, V, boolean>, 'transform' | 'query' | 'ignoreCase' | 'matchExact'>, item: V, propertyName?: string): boolean;
+/**
+ * Utility for use with {@link search} function
+ *
+ * @returns match index (`-1` means didn't match)
+ */
+declare function matchObjOrProp<K, V>(// extends Record<string, unknown>
+{ query, ignoreCase, matchExact, transform, }: Pick<SearchOptions<K, V, boolean>, 'transform' | 'query' | 'ignoreCase' | 'matchExact'>, item: V, propertyName?: string): number;
 
 type SliceMapTransform<Data, Value, Key> = (item: Value, key: Key, data: Data) => Value;
 type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
@@ -1356,4 +1374,4 @@ declare const HASH_REGEX: RegExp;
  */
 declare const strToArr: (value: unknown, seperator?: string) => string[];
 
-export { type ArrayComparator, type AsyncFn, type CreateTuple, type CurriedArgs, type Curry, type DeferredOptions, type DropFirst, type DropFirstN, type DropLast, EMAIL_REGEX, type EntryComparator, type FindOptions, HASH_REGEX, HEX_REGEX, type IfPromiseAddValue, type IsFiniteTuple, type IsOptional, type IterableList, type KeepFirst, type KeepFirstN, type KeepOptionals, type KeepRequired, type MakeOptional, type MinLength, type NegativeNumber, type OptionalIf, type PositiveNumber, type PositiveNumberWithZero, type ReadOnlyAllowAddFn, ReadOnlyArrayHelper, type ReadOnlyConfig, type SearchOptions, type Slice, type SliceMapOptions, type SliceMapTransform, type SortOptions, type ThrottleOptions, type TimeoutId, type TupleMaxLength, type TupleWithAlt, type ValueOrFunc, type ValueOrPromise, arrReadOnly, arrReverse, arrToMap, arrUnique, asAny, clearClutter, copyToClipboard, curry, debounce, deferred, fallbackIfFails, filter, find, forceCast, getEntries, getKeys, getSize, getUrlParam, getValues, is, isArr, isArr2D, isArrLike, isArrLikeSafe, isArrObj, isArrUnique, isAsyncFn, isBool, isDate, isDateValid, isDefined, isEmpty, isEmptySafe, isEnvBrowser, isEnvNode, isEnvTouchable, isError, isFn, isInteger, isMap, isMapObj, isNumber, isObj, isPositiveInteger, isPositiveNumber, isPromise, isRegExp, isSet, isStr, isSymbol, isUint8Arr, isUrl, isUrlValid, mapJoin, matchItemOrProp, noop, noopAsync, objClean, objCopy, objCreate, objHasKeys, objKeys, objReadOnly, objSetProp, objSetPropUndefined, objSort, objWithoutKeys, randomInt, reverse, search, sliceMap, sort, strToArr, throttled, toDatetimeLocal };
+export { type ArrayComparator, type AsyncFn, type CreateTuple, type CurriedArgs, type Curry, type DeferredOptions, type DropFirst, type DropFirstN, type DropLast, EMAIL_REGEX, type EntryComparator, type FindOptions, HASH_REGEX, HEX_REGEX, type IfPromiseAddValue, type IsFiniteTuple, type IsOptional, type IterableList, type KeepFirst, type KeepFirstN, type KeepOptionals, type KeepRequired, type MakeOptional, type MinLength, type NegativeNumber, type OptionalIf, type PositiveNumber, type PositiveNumberWithZero, type ReadOnlyAllowAddFn, ReadOnlyArrayHelper, type ReadOnlyConfig, type SearchOptions, type Slice, type SliceMapOptions, type SliceMapTransform, type SortOptions, type ThrottleOptions, type TimeoutId, type TupleMaxLength, type TupleWithAlt, type ValueOrFunc, type ValueOrPromise, arrReadOnly, arrReverse, arrToMap, arrUnique, asAny, clearClutter, copyToClipboard, curry, debounce, deferred, fallbackIfFails, filter, find, forceCast, getEntries, getKeys, getSize, getUrlParam, getValues, is, isArr, isArr2D, isArrLike, isArrLikeSafe, isArrObj, isArrUnique, isAsyncFn, isBool, isDate, isDateValid, isDefined, isEmpty, isEmptySafe, isEnvBrowser, isEnvNode, isEnvTouchable, isError, isFn, isInteger, isMap, isMapObj, isNumber, isObj, isPositiveInteger, isPositiveNumber, isPromise, isRegExp, isSet, isStr, isSymbol, isUint8Arr, isUrl, isUrlValid, mapJoin, matchObjOrProp, noop, noopAsync, objClean, objCopy, objCreate, objHasKeys, objKeys, objReadOnly, objSetProp, objSetPropUndefined, objSort, objWithoutKeys, randomInt, reverse, search, sliceMap, sort, strToArr, throttled, toDatetimeLocal };

package/dist/index.js

@@ -579,11 +579,23 @@ var search = (data, options) => {
   const result = isMap(options == null ? void 0 : options.result) ? options.result : /* @__PURE__ */ new Map();
   const asMap = (_a = options == null ? void 0 : options.asMap) != null ? _a : search.defaultOptions.asMap;
   if (ignore) return asMap ? result : getValues_default(result);
-  options = objCopy(search.defaultOptions, options, [], "empty");
-  const { ignoreCase, limit = Infinity, matchAll, matchExact } = options;
+  options = objCopy(
+    search.defaultOptions,
+    options,
+    [],
+    "empty"
+    // override `option` property with default value when "empty" (undefined, null, '',....)
+  );
+  const {
+    ignoreCase,
+    limit = Infinity,
+    matchAll,
+    matchExact,
+    ranked
+  } = options;
   let { query } = options;
   const qIsStr = isStr(query);
-  const qIsRegExp = !qIsStr && isRegExp(query);
+  const qIsRegExp = isRegExp(query);
   const qKeys = fallbackIfFails_default(Object.keys, [query], []);
   if (ignoreCase && !matchExact && !qIsRegExp) {
     query = qIsStr ? query.toLowerCase() : objCreate(
@@ -594,15 +606,45 @@ var search = (data, options) => {
     );
   }
   options.query = query;
-  const entries = data.entries();
-  for (const [dataKey, dataValue] of entries) {
-    if (result.size >= limit) break;
-    const matched = qIsStr || qIsRegExp ? matchItemOrProp(options, dataValue, void 0) : qKeys[matchAll ? "every" : "some"](
-      (key) => matchItemOrProp(options, dataValue, key)
-      // search specific properties
-    );
-    if (!matched) continue;
-    result.set(dataKey, dataValue);
+  if (!ranked) {
+    for (const [dataKey, dataValue] of data.entries()) {
+      if (result.size >= limit) break;
+      const matched = qIsStr || qIsRegExp ? (
+        // global search across all properties
+        matchObjOrProp(options, dataValue, void 0) >= 0
+      ) : (
+        // field-specific search
+        qKeys[matchAll ? "every" : "some"](
+          (key) => matchObjOrProp(options, dataValue, key) >= 0
+        )
+      );
+      if (!matched) continue;
+      result.set(dataKey, dataValue);
+    }
+  } else {
+    const preRankedResults = [];
+    for (const [dataKey, dataValue] of data.entries()) {
+      let matchIndex = -1;
+      if (qIsStr || qIsRegExp) {
+        matchIndex = matchObjOrProp(options, dataValue, void 0);
+        matchIndex >= 0 && preRankedResults.push([matchIndex, dataKey, dataValue]);
+        continue;
+      }
+      const indexes = [];
+      const match = qKeys[matchAll ? "every" : "some"](
+        // field-specific search
+        (key) => {
+          const index = matchObjOrProp(options, dataValue, key);
+          indexes.push(index);
+          return index >= 0;
+        }
+      );
+      if (!match) continue;
+      matchIndex = // eslint-disable-next-line @typescript-eslint/prefer-find
+      indexes.sort((a, b) => a - b).filter((n) => n !== -1)[0];
+      matchIndex >= 0 && preRankedResults.push([matchIndex, dataKey, dataValue]);
+    }
+    preRankedResults.sort((a, b) => a[0] - b[0]).slice(0, limit).forEach(([_, key, value]) => result.set(key, value));
   }
   return asMap ? result : getValues_default(result);
 };
@@ -611,36 +653,37 @@ search.defaultOptions = {
   ignoreCase: true,
   limit: Infinity,
   matchAll: false,
-  matchExact: false
+  ranked: false,
+  transform: true
 };
-function matchItemOrProp({
+function matchObjOrProp({
   query,
   ignoreCase,
   matchExact,
-  transform
+  transform = true
 }, item, propertyName) {
-  const fuzzy = isStr(query) || isRegExp(query) || propertyName === void 0;
-  const keyword = fuzzy ? query : query[propertyName];
-  const propVal = fuzzy || !isObj(item) ? item : item[propertyName];
-  let value = fallbackIfFails_default(
-    () => {
-      var _a;
-      return isFn(transform) ? transform(
-        item,
-        fuzzy ? void 0 : propVal,
-        propertyName
-      ) : isObj(propVal, false) ? JSON.stringify(
-        isArrLike(propVal) ? [...propVal.values()] : Object.values(propVal)
-      ) : (_a = propVal == null ? void 0 : propVal.toString) == null ? void 0 : _a.call(propVal);
-    },
+  var _a, _b;
+  const global = isStr(query) || isRegExp(query) || propertyName === void 0;
+  const keyword = global ? query : query[propertyName];
+  const propVal = global || !isObj(item) ? item : item[propertyName];
+  const value = fallbackIfFails_default(
+    () => isFn(transform) ? transform(
+      item,
+      global ? void 0 : propVal,
+      propertyName
+    ) : matchExact && transform === false ? propVal : isObj(propVal, false) ? JSON.stringify(
+      isArrLike(propVal) ? [...propVal.values()] : Object.values(propVal)
+    ) : String(propVal != null ? propVal : ""),
     [],
     ""
   );
-  if (!(value == null ? void 0 : value.trim())) return false;
-  if (isRegExp(keyword)) return keyword.test(`${value}`);
-  if (ignoreCase && !matchExact) value = value.toLowerCase();
-  if (value === keyword) return true;
-  return !matchExact && `${value}`.includes(String(keyword));
+  if (value === keyword) return 0;
+  if (matchExact) return -1;
+  let valueStr = String(value);
+  if (!valueStr.trim()) return -1;
+  if (isRegExp(keyword)) return (_b = (_a = valueStr.match(keyword)) == null ? void 0 : _a.index) != null ? _b : -1;
+  if (ignoreCase) valueStr = valueStr.toLowerCase();
+  return valueStr.indexOf(String(keyword));
 }
 var search_default = search;
 
@@ -924,7 +967,7 @@ export {
   isUrl,
   isUrlValid,
   mapJoin,
-  matchItemOrProp,
+  matchObjOrProp,
   noop,
   noopAsync,
   objClean,

package/package.json

@@ -42,5 +42,5 @@
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.5"
+	"version": "1.0.6"
 }