@superutils/core 1.0.5 → 1.0.7

package/README.md

@@ -15,7 +15,7 @@ For full API reference check out the [docs page](https://alien45.github.io/super
     - [`is`](#is): Type checkers
     - [`deferred()`](#deferred): Debounce callbacks
     - [`throttle()`](#throttle): Throttle callbacks
-    - [`fallbackIfFails()`](#fallback-if-fails): Gracefully invoke functions
+    - [`fallbackIfFails()`](#fallback-if-fails): Gracefully invoke functions or promises with a fallback
     - [`objCopy()`](#obj-copy): Deep-copy objects
     - [`search()`](#search): Search iterable collections
 
@@ -110,9 +110,9 @@ handleChange({ target: { value 3 } }) // will be ignored
 
 <div id="fallback-if-fails"></div>
 
-### `fallbackIfFails(fn, args, fallback)`: gracefully invoke functions
+### `fallbackIfFails(target, args, fallback)`: Gracefully invoke functions or promises with a fallback
 
-Based on the function provided `fallbackIfFails` will either execute synchronously or asynchronously.
+The `fallbackIfFails` function can wrap a standard function, a promise-returning function, or a promise directly. It automatically handles both synchronous execution and asynchronous resolution, providing a fallback value if the function throws an error or the promise is rejected.
 
 #### Sync operations:
 
@@ -149,6 +149,13 @@ fallbackIfFails(
 	{ products: [] }, // Fallback value to be returned when function throws an error.
 ).then(console.log)
 // Prints the result when request is successful or fallback value when request fails
+
+
+// use a promise
+fallbackIfFails(
+	Promise.reject('error'),
+	[], // 
+)
 ```
 
 <div id="obj-copy"></div>
@@ -222,7 +229,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:
@@ -249,13 +256,13 @@ search(data, {
 	asMap: false, // Result type: true => Map (default, keys preserved), false => Array
 	ignoreCase: false, // For text case-sensitivity
 	limit: 10, // Number of items returned. Default: no limit
-	matchExact: true, // true: full text search. false (default): partial matching
+	matchExact: true, // true: match exact value. false (default): partial matching
 	matchAll: true, // if true, item will be matched only when all of the query properties match
 	query: {
 		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

@@ -24,15 +24,19 @@ type CreateTuple<T, Length extends number, Output extends readonly unknown[] = [
  * @template TData The final return type.
  */
 type Curry<TData, TParams extends unknown[]> = <TArgs extends unknown[]>(...args: TArgs & KeepFirstN<TParams, TArgs['length']>) => DropFirstN<TParams, TArgs['length']> extends [unknown, ...unknown[]] ? Curry<TData, DropFirstN<TParams, TArgs['length']>> : TData;
+type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc extends (...args: any[]) => unknown, TArity extends number> = TArgsIsFinite extends false ? CreateTuple<Parameters<TFunc>[number], TArity> : KeepFirstN<[
+    ...KeepRequired<TArgs>,
+    ...KeepOptionals<TArgs, true, undefined>
+], TArity>;
 /**
- * Deferred function config
+ * Deferred function options
  */
-interface DeferredOptions<ThisArg = unknown> {
+type DeferredOptions<ThisArg = unknown> = {
     leading?: boolean | 'global';
     onError?: (err: unknown) => ValueOrPromise<unknown>;
     thisArg?: ThisArg;
     tid?: TimeoutId;
-}
+};
 /**
  * Drop the first item from an array/tuple and keep the rest
  * ---
@@ -249,10 +253,6 @@ type ValueOrPromise<T> = T | Promise<T>;
 declare function curry<TData, TArgs extends unknown[], TArgsIsFinite extends boolean = IsFiniteTuple<TArgs>, TArity extends TArgs['length'] = TArgsIsFinite extends true ? TupleMaxLength<TArgs> : number>(func: (...args: TArgs) => TData, ...[arity]: TArgsIsFinite extends true ? [arity?: TArity] : [
     arity: TArity
 ]): Curry<TData, CurriedArgs<TArgs, TArgsIsFinite, (...args: TArgs) => TData, TArity>>;
-type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc extends (...args: any[]) => unknown, TArity extends number> = TArgsIsFinite extends false ? CreateTuple<Parameters<TFunc>[number], TArity> : KeepFirstN<[
-    ...KeepRequired<TArgs>,
-    ...KeepOptionals<TArgs, true, undefined>
-], TArity>;
 
 /**
  * @function deferred AKA debounce
@@ -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

@@ -1,14 +1,9 @@
-// src/forceCast.ts
-var asAny = (x) => x;
-var forceCast = (x) => x;
-var forceCast_default = forceCast;
-
 // src/curry.ts
 function curry(func, ...[arity = func.length]) {
   const curriedFn = (...args) => {
     const _args = args;
-    if (_args.length >= arity) return func(...forceCast_default(args));
-    return (...nextArgs) => asAny(curriedFn)(
+    if (_args.length >= arity) return func(...args);
+    return (...nextArgs) => curriedFn(
       ..._args,
       ...nextArgs
     );
@@ -248,6 +243,10 @@ function debounce(...args) {
   return deferred_default(...args);
 }
 
+// src/forceCast.ts
+var asAny = (x) => x;
+var forceCast = (x) => x;
+
 // src/throttled.ts
 var throttled = (callback, delay = 50, config = {}) => {
   const { defaults: d } = throttled;
@@ -346,7 +345,7 @@ var objCopy = (input, output, ignoreKeys, override = false, recursive = true) =>
     const value = input[key];
     const skip = _output.hasOwnProperty(key) && (override === "empty" ? !isEmpty(_output[key]) : isFn(override) ? !override(key, _output[key], value) : true);
     if (skip) continue;
-    const isPrimitive = [void 0, null, Infinity, NaN].includes(asAny(value)) || !isObj(value, false);
+    const isPrimitive = [void 0, null, Infinity, NaN].includes(value) || !isObj(value, false);
     if (isPrimitive) {
       _output[key] = value;
       continue;
@@ -356,26 +355,28 @@ var objCopy = (input, output, ignoreKeys, override = false, recursive = true) =>
         case Array.prototype:
           return clone(value, "[]");
         case ArrayBuffer.prototype:
-          return asAny(value).slice(0);
+          return value.slice(0);
         case Date.prototype:
-          return new Date(asAny(value).getTime());
+          return new Date(value.getTime());
         case Map.prototype:
           return new Map(
             clone(
-              Array.from(asAny(value)),
+              Array.from(
+                value
+              ),
               "[]"
             )
           );
         case RegExp.prototype:
-          return new RegExp(asAny(value));
+          return new RegExp(value);
         case Set.prototype:
           return new Set(
-            clone(Array.from(asAny(value)))
+            clone(Array.from(value))
           );
         case Uint8Array.prototype:
-          return new Uint8Array([...asAny(value)]);
+          return new Uint8Array([...value]);
         case URL.prototype:
-          return new URL(asAny(value));
+          return new URL(value);
         default:
           break;
       }
@@ -579,11 +580,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 +607,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 +654,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 +968,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.7"
 }