@superutils/core 1.0.4 → 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

@@ -27,7 +27,7 @@ type Curry<TData, TParams extends unknown[]> = <TArgs extends unknown[]>(...args
 /**
  * Deferred function config
  */
-interface DeferredConfig<ThisArg = unknown> {
+interface DeferredOptions<ThisArg = unknown> {
     leading?: boolean | 'global';
     onError?: (err: unknown) => ValueOrPromise<unknown>;
     thisArg?: ThisArg;
@@ -283,7 +283,7 @@ type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc e
  *
  */
 declare const deferred: {
-    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: DeferredConfig<ThisArg>): (...args: TArgs) => void;
+    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: DeferredOptions<ThisArg>): (...args: TArgs) => void;
     defaults: {
         /**
          * Set the default value of argument `leading` for the `deferred` function.
@@ -400,7 +400,7 @@ declare const isArrLike: (x: any) => x is typeof x extends (infer Value)[] ? Val
  * Check if value is convertible to an array by using `Array.from(x)` even if it comes from a different realm
  * (eg: iframe, iframes, worker contexts, node vm contexts, browser extensions).
  *
- * Caution: much slower than {@link isArrLike()} due to use of `Object.prototype.toString.call()`
+ * Caution: much slower than {@link isArrLike} due to use of `Object.prototype.toString.call()`
  */
 declare const isArrLikeSafe: <T = unknown, MapKey = unknown>(x: unknown) => x is Set<T> | Map<MapKey, T> | T[];
 /** Check if all values in the array are unique */
@@ -644,7 +644,7 @@ declare const is: {
 declare function noop(): void;
 declare function noopAsync(): Promise<void>;
 
-type ThrottleConfig<ThisArg = unknown> = {
+type ThrottleOptions<ThisArg = unknown> = {
     onError?: (err: unknown) => ValueOrPromise<unknown>;
     thisArg?: ThisArg;
     trailing?: boolean;
@@ -662,7 +662,7 @@ type ThrottleConfig<ThisArg = unknown> = {
  * @param   config.trailing (optional) whether to enable trailing edge execution. Default: `true`
  */
 declare const throttled: {
-    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: ThrottleConfig<ThisArg>): (...args: TArgs) => void;
+    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: ThrottleOptions<ThisArg>): (...args: TArgs) => void;
     /**
      * Set the default values
      * This change is applicable application-wide and only applies to any new invocation of `throttle()`.
@@ -712,25 +712,34 @@ declare const objClean: <T extends Record<PropertyKey, unknown>, Key extends key
  * Deep-copy an object to another object
  *
  * @param input input object
+ * @param _output (optional) output object
  * @param ignoreKeys (optional) input peroperties to be ignored. Prevents output's property to be overriden.
  *
  * For child object properties use "." (dot) separated path.
  *
  * Eg: `"child.grandchild1"` where input is `{ child: { grandchild1: 1, grandchild2: 2 }}`
  *
- * @param output (optional) output object
- * @param override (optional) whether to allow override output (if provided) properties.
+ * @param override (optional) whether to allow override output properties.
+ * This will only be used if `output` object is provided and has own property.
  * Accepted values:
- * `true`: input property will override output property
- * `false`: no overriding if output contains the property. Even if the property value is `undefined`.
- * `"empty"`: only allow overriding output property if it's value is empty by using {@link isEmpty}.
+ * - `true`: input property will override output property
+ * - `false`: no overriding if output contains the property. Even if the property value is `undefined`.
+ * - `"empty"`: only allow overriding output property if it's value is empty by using {@link isEmpty}.
+ * - `function`: decide whether to override on a per property basis.
+ *
+ * Function Arguments:
+ *     1. key: current property name/key
+ *     2. outputValue: `output` property value
+ *     3. inputValue: `input` property value
  *
  * Default: `false`
  *
+ * @param reverse (optional) whether to reverse sort object properties. Default: `false`
+ *
  *
  * @returns copied and/or merged object
  */
-declare const objCopy: <Key extends string | symbol, T extends Record<Key, unknown>, IgnoredKey extends Key | string>(input: T, output?: Record<PropertyKey, unknown>, ignoreKeys?: IgnoredKey[] | Set<IgnoredKey>, override?: boolean | "empty", recursive?: boolean) => Record<PropertyKey, unknown>;
+declare const objCopy: <Key extends PropertyKey, InValue, OutValue, IgnoredKey extends Key | string>(input: Record<Key, InValue>, output?: Record<PropertyKey, OutValue>, ignoreKeys?: IgnoredKey[] | Set<IgnoredKey>, override?: boolean | "empty" | ((key: Key, outputValue: OutValue, inputValue: InValue) => boolean), recursive?: boolean) => Record<PropertyKey, unknown>;
 
 /**
  * Creates an object from an array of keys and a corresponding array of values.
@@ -760,6 +769,15 @@ declare const objCopy: <Key extends string | symbol, T extends Record<Key, unkno
  */
 declare const objCreate: <V, K extends PropertyKey, RV, RK extends PropertyKey, Result extends Record<K | RK, V | RV>>(keys?: K[], values?: V[], result?: Result) => Result;
 
+/**
+ * Checks if all the supplied keys exist in an object
+ *
+ * @param input
+ * @param keys
+ * @param equireValue (optional) whether each property should have some value.
+ */
+declare function objHasKeys(input?: object | unknown[], keys?: PropertyKey[], requireValue?: boolean): boolean;
+
 /**
  * Get object property names/keys
  *
@@ -837,10 +855,11 @@ declare const objWithoutKeys: (input: unknown, keys: string[], output?: Record<P
 declare const arrReadOnly: <T>(arr: T[], config?: Omit<ReadOnlyConfig<T[]>, "revoke">) => T[];
 
 /**
+ * @ignore exclude from documentation
  * Helper class for creating read-only arrays.
  *
  * Caution: This class can by itself only make the array partially read-only.
- * Use {@link arrReadOnly()} instead.
+ * Use {@link arrReadOnly} instead.
  */
 declare class ReadOnlyArrayHelper<T> extends Array<T> {
     readonly config: Omit<ReadOnlyConfig<T[]>, 'revoke'>;
@@ -852,16 +871,6 @@ declare class ReadOnlyArrayHelper<T> extends Array<T> {
     shift: () => T;
     splice: (..._ignoredArgs: unknown[]) => never[];
     unshift: (..._ignoredArgs: T[]) => number;
-    reduce: {
-        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
-        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T): T;
-        <U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;
-    };
-    reduceRight: {
-        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T): T;
-        (callbackfn: (previousValue: T, currentValue: T, currentIndex: number, array: T[]) => T, initialValue: T): T;
-        <U>(callbackfn: (previousValue: U, currentValue: T, currentIndex: number, array: T[]) => U, initialValue: U): U;
-    };
 }
 
 /**
@@ -905,9 +914,9 @@ declare const arrReverse: <T = unknown>(arr: T[], reverse?: boolean, newArray?:
  * const map = arrToMap(arr, (item: Item) => item.key, 1) // Map<number, Item>
  * ```
  */
+declare function arrToMap<T extends unknown[], FlatDepth extends number = 0, MapItem = FlatArray<T, FlatDepth>, KeyProp extends keyof MapItem = keyof MapItem>(arr: T, key: KeyProp, flatDepth?: FlatDepth): Map<MapItem[KeyProp], MapItem>;
 declare function arrToMap<T extends unknown[], FlatDepth extends number = 0>(arr: T, flatDepth?: FlatDepth): Map<number, FlatArray<T, FlatDepth>>;
 declare function arrToMap<T extends unknown[], FlatDepth extends number = 0, MapItem = FlatArray<T, FlatDepth>, MapKey = unknown>(arr: T, key: (item: MapItem, index: number, flatArr: MapItem[]) => MapKey, flatDepth?: FlatDepth): Map<MapKey, MapItem>;
-declare function arrToMap<T extends unknown[], FlatDepth extends number = 0, MapItem = FlatArray<T, FlatDepth>, KeyProp extends keyof MapItem = keyof MapItem>(arr: T, key: KeyProp, flatDepth?: FlatDepth): Map<MapItem[KeyProp], MapItem>;
 
 /**
  * @function	arrUnique
@@ -957,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` */
@@ -965,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);
 };
 
 /**
@@ -987,6 +1008,12 @@ type SearchOptions<K, V, AsMap extends boolean = false> = {
  *
  * @param data
  * @param predicate callback function to filter values
+ * Parameters:
+ * 1. `item`: current item
+ * 2. `key`: index/key
+ * 3. `data`: value provided in the first argument (`data`)
+ * @param limit	(optional) limit number of results
+ * @param arArray
  *
  * @returns new Map with filtered items
  *
@@ -1007,7 +1034,7 @@ type SearchOptions<K, V, AsMap extends boolean = false> = {
  * // }
  * ```
  */
-declare const filter: <K, V, AsArray extends boolean = false, Result = AsArray extends true ? V[] : Map<K, V>>(data: IterableList<K, V>, predicate: (value: V, key: K, data: IterableList<K, V>) => boolean, limit?: number, asArray?: AsArray, result?: Map<K, V>) => Result;
+declare const filter: <K, V, AsArray extends boolean = false, Result = AsArray extends true ? V[] : Map<K, V>>(data: IterableList<K, V>, predicate: (item: V, key: K, data: IterableList<K, V>) => boolean, limit?: number, asArray?: AsArray, result?: Map<K, V>) => Result;
 
 /**
  * Finds a first item matching criteria in an {@link IterableList}.
@@ -1070,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:
@@ -1082,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`.
@@ -1116,19 +1145,23 @@ 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 SliceMapCallback<Data, Value, Key> = (item: Value, key: Key, data: Data) => Value;
+type SliceMapTransform<Data, Value, Key> = (item: Value, key: Key, data: Data) => Value;
 type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
     /** Whether to return the result as a Map (preserving original keys) or an Array */
     asMap?: AsMap;
-    /** callback to transform each item */
-    transform?: SliceMapCallback<Data, Value, Key>;
+    /** Callback to transform each item from the selected range */
+    transform?: SliceMapTransform<Data, Value, Key>;
     /** End index (exclusive). Default: `undefined` (end of the list) */
     end?: number;
     /** Whether to exclude item if value is `undefined | null` */
@@ -1140,9 +1173,14 @@ type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
  * Slice an iterable list and map the values into an Array/Map
  *
  * @param data		Array, Map, Set...
- * @param start		Default: `0`
- * @param end		(optional) last index - exclusive. Default: index of the last item
- * @param callback	to be executed on each item within the set range.
+ * @param options	One of the following is required to create a new list:
+ * 1. A callback function {@link SliceMapTransform} to transform all items.
+ * 2. Advanced options {@link SliceMapOptions}.
+ * @param options.asMap	(optional) whether return a Map or Array.
+ * @param options.end	(optional) End index (exclusive). Default: `undefined` (end of the list)
+ * @param options.ignoreEmpty (optional) Whether to exclude item if value is `undefined | null`
+ * @param options.start	(optional) Default: `0`
+ * @param options.transform	(optional)
  *
  * If callback throws error or returnes `undefined`, the item will be ignored.
  *
@@ -1153,7 +1191,7 @@ type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
  *
  * @returns Array/Map
  */
-declare const sliceMap: <Data extends IterableList, Key = Data extends IterableList<infer Key_1, unknown> ? Key_1 : never, Value = Data extends IterableList<unknown, infer Value_1> ? Value_1 : never, AsMap extends boolean = false>(data: Data, options?: SliceMapOptions<Data, Value, Key, AsMap> | SliceMapCallback<Data, Value, Key>) => AsMap extends false ? Value[] : Map<Key, Value>;
+declare const sliceMap: <Data extends IterableList, Key = Data extends IterableList<infer Key_1, unknown> ? Key_1 : never, Value = Data extends IterableList<unknown, infer Value_1> ? Value_1 : never, AsMap extends boolean = false, Result = AsMap extends false ? Value[] : Map<Key, Value>>(data: Data, options?: SliceMapOptions<Data, Value, Key, AsMap> | SliceMapTransform<Data, Value, Key>) => Result;
 
 type EntryComparator<K, V> = (a: [K, V], b: [K, V]) => number;
 type ArrayComparator<V> = (a: V, b: V) => number;
@@ -1267,6 +1305,13 @@ declare const mapJoin: <K, V>(...inputs: (Map<K, V> | [K, V][])[]) => Map<K, V>;
  */
 declare const randomInt: (min?: number, max?: number) => number;
 
+/** Describes a number type with negative values only */
+type NegativeNumber<N extends number = number> = `${N}` extends `-${string}` ? N : never;
+/** Describes a number type with positive values excluding `0`  */
+type PositiveNumber<N extends number = number> = `${N}` extends `-${string}` | '0' ? never : N;
+/** Describes a number type with positive values and `0`  */
+type PositiveNumberWithZero<N extends number = number> = `${N}` extends `-${string}` ? never : N;
+
 /**
  * Clears clutter from strings
  *
@@ -1319,4 +1364,14 @@ declare const EMAIL_REGEX: RegExp;
 declare const HEX_REGEX: RegExp;
 declare const HASH_REGEX: RegExp;
 
-export { type ArrayComparator, type AsyncFn, type CreateTuple, type CurriedArgs, type Curry, type DeferredConfig, 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 OptionalIf, type ReadOnlyAllowAddFn, ReadOnlyArrayHelper, type ReadOnlyConfig, type SearchOptions, type Slice, type SliceMapCallback, type SliceMapOptions, type SortOptions, type ThrottleConfig, 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, objKeys, objReadOnly, objSetProp, objSetPropUndefined, objSort, objWithoutKeys, randomInt, reverse, search, sliceMap, sort, throttled, toDatetimeLocal };
+/**
+ * Convert comma separated strings to array
+ *
+ * @param value value to convert
+ * @param seperator (optional) only used when value is a string. Default: `","`
+ *
+ * @returns Array
+ */
+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, 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

@@ -195,15 +195,12 @@ var is = {
 // src/fallbackIfFails.ts
 var fallbackIfFails = (target, args, fallbackValue) => {
   let result;
-  let asPromise = false;
   try {
     result = !isFn(target) ? target : target(...isFn(args) ? args() : args);
     if (!isPromise(result)) return result;
-    asPromise = true;
     return result.catch((err) => getAltValCb(err, fallbackValue));
   } catch (error) {
-    result = getAltValCb(error, fallbackValue);
-    return asPromise && !isPromise(result) ? Promise.resolve(result) : result;
+    return getAltValCb(error, fallbackValue);
   }
 };
 var fallbackIfFails_default = fallbackIfFails;
@@ -298,7 +295,7 @@ var objClean = (obj, keys, ignoreIfNotExist = true) => {
   const result = {};
   if (!isObj(obj) || !isArr(keys)) return result;
   const uniqKeys = arrUnique(
-    keys.map((x) => isStr(x) ? `${x}`.split(".")[0] : x)
+    keys.map((x) => String(x).split(".")[0])
   ).sort();
   for (const key of uniqKeys) {
     if (ignoreIfNotExist && !obj.hasOwnProperty(key)) continue;
@@ -338,8 +335,8 @@ var objKeys_default = objKeys;
 // src/obj/objCopy.ts
 var clone = (value, fallback = "null") => JSON.parse(fallbackIfFails_default(JSON.stringify, [value], fallback));
 var objCopy = (input, output, ignoreKeys, override = false, recursive = true) => {
-  if (!isObj(output)) output = {};
-  if (!isObj(input)) return output;
+  const _output = isObj(output) ? output : {};
+  if (!isObj(input)) return _output;
   const _ignoreKeys = new Set(ignoreKeys != null ? ignoreKeys : []);
   const inKeys = objKeys_default(input, true, true).filter(
     (x) => !_ignoreKeys.has(x)
@@ -347,14 +344,14 @@ var objCopy = (input, output, ignoreKeys, override = false, recursive = true) =>
   for (const _key of inKeys) {
     const key = _key;
     const value = input[key];
-    const skip = output.hasOwnProperty(key) && (!override || override === "empty" && !isEmpty(output[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);
     if (isPrimitive) {
-      output[key] = value;
+      _output[key] = value;
       continue;
     }
-    output[key] = (() => {
+    _output[key] = (() => {
       switch (Object.getPrototypeOf(value)) {
         case Array.prototype:
           return clone(value, "[]");
@@ -384,19 +381,19 @@ var objCopy = (input, output, ignoreKeys, override = false, recursive = true) =>
       }
       if (isSymbol(key) || !recursive) return clone(value);
       const ignoreChildKeys = [..._ignoreKeys].map(
-        (x) => !isSymbol(x) && x.startsWith(key.concat(".")) && x.split(key.concat("."))[1]
+        (x) => String(x).startsWith(String(key).concat(".")) && String(x).split(String(key).concat("."))[1]
       ).filter(Boolean);
       if (!ignoreChildKeys.length) return clone(value);
       return objCopy(
         value,
-        output[key],
+        _output[key],
         ignoreChildKeys,
         override,
         recursive
       );
     })();
   }
-  return output;
+  return _output;
 };
 
 // src/obj/objCreate.ts
@@ -409,6 +406,16 @@ var objCreate = (keys = [], values = [], result) => {
   return result;
 };
 
+// src/obj/objHasKeys.ts
+function objHasKeys(input = {}, keys = [], requireValue = false) {
+  if (!isObj(input) || !isArr(keys)) return false;
+  for (const key of keys) {
+    if (!input.hasOwnProperty(key)) return false;
+    if (requireValue && isEmpty(input[key])) return false;
+  }
+  return true;
+}
+
 // src/obj/objReadOnly.ts
 var objReadOnly = (obj, config) => {
   if (!isObj(obj, false)) obj = {};
@@ -501,10 +508,10 @@ var ReadOnlyArrayHelper = class extends Array {
     this.shift = () => this.ignoreOrThrow(this[0]);
     this.splice = (..._ignoredArgs) => this.ignoreOrThrow([]);
     this.unshift = (..._ignoredArgs) => this.ignoreOrThrow(this.length);
-    // fromAsync = super.fromAsync
-    this.reduce = super.reduce;
-    this.reduceRight = super.reduceRight;
   }
+  // fromAsync = super.fromAsync
+  // reduce = super.reduce
+  // reduceRight = super.reduceRight
 };
 
 // src/arr/arrReverse.ts
@@ -532,9 +539,10 @@ function arrToMap(arr, key, flatDepth = 0) {
 var arrUnique = (arr, flatDepth = 0) => !isArr(arr) ? [] : Array.from(new Set(arr.flat(flatDepth)));
 
 // src/iterable/filter.ts
-var filter = (data, predicate, limit = Infinity, asArray = false, result = /* @__PURE__ */ new Map()) => {
+var filter = (data, predicate, limit, asArray, result) => {
   var _a;
   if (!isMap(result)) result = /* @__PURE__ */ new Map();
+  if (!isPositiveInteger(limit)) limit = Infinity;
   for (const [key, item] of ((_a = data == null ? void 0 : data.entries) == null ? void 0 : _a.call(data)) || []) {
     if (result.size >= limit) break;
     fallbackIfFails_default(predicate != null ? predicate : item, [item, key, data], false) && result.set(key, item);
@@ -571,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(
@@ -586,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);
 };
@@ -603,37 +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) {
   var _a, _b;
-  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 _a2;
-      return isFn(transform) ? transform(
-        item,
-        fuzzy ? void 0 : propVal,
-        propertyName
-      ) : isObj(propVal, false) ? JSON.stringify(
-        isArrLike(propVal) ? [...propVal.values()] : Object.values(propVal)
-      ) : (_a2 = propVal == null ? void 0 : propVal.toString) == null ? void 0 : _a2.call(propVal);
-    },
+  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((_b = (_a = keyword == null ? void 0 : keyword.toString) == null ? void 0 : _a.call(keyword)) != null ? _b : "");
+  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;
 
@@ -669,9 +719,13 @@ var reverse = (data, reverse2 = true, newInstance = false) => {
   if (!dataType) return [];
   const arr = dataType === 1 ? !newInstance ? data : [...data] : dataType === 2 ? [...data.entries()] : [...data.values()];
   if (reverse2) arr.reverse();
-  if (dataType === 1) return arr;
-  if (newInstance || !("clear" in data && isFn(data.clear))) {
-    return dataType === 2 ? new Map(arr) : dataType === 3 && new Set(arr) || [];
+  switch (dataType) {
+    case 1:
+      return arr;
+    case 2:
+    case 3:
+      if (newInstance || !("clear" in data && isFn(data.clear)))
+        return dataType === 2 ? new Map(arr) : new Set(arr);
   }
   (_a = data == null ? void 0 : data.clear) == null ? void 0 : _a.call(data);
   for (const item of arr)
@@ -782,7 +836,7 @@ var copyToClipboard = (str) => fallbackIfFails(
   () => navigator.clipboard.writeText(str).then(() => 1),
   [],
   // If clipboard API is not available or fails, use the fallback method
-  () => Promise.resolve(copyLegacy(str))
+  () => Promise.resolve(copyLegacy(str) ? 2 : 0)
 );
 var copyLegacy = (str) => fallbackIfFails(
   () => {
@@ -795,11 +849,11 @@ var copyLegacy = (str) => fallbackIfFails(
     el.select();
     const success = document.execCommand("copy");
     document.body.removeChild(el);
-    return success ? 2 : 0;
+    return success;
   },
   [],
-  0
-  // On error, resolve with 0
+  false
+  // On error, return false
 );
 
 // src/str/getUrlParam.ts
@@ -851,6 +905,9 @@ var EMAIL_REGEX = new RegExp(
 );
 var HEX_REGEX = /^0x[0-9a-f]+$/i;
 var HASH_REGEX = /^0x[0-9a-f]{64}$/i;
+
+// src/str/strToArr.ts
+var strToArr = (value, seperator = ",") => typeof value === "string" && value.split(seperator).filter(Boolean) || [];
 export {
   EMAIL_REGEX,
   HASH_REGEX,
@@ -910,12 +967,13 @@ export {
   isUrl,
   isUrlValid,
   mapJoin,
-  matchItemOrProp,
+  matchObjOrProp,
   noop,
   noopAsync,
   objClean,
   objCopy,
   objCreate,
+  objHasKeys,
   objKeys,
   objReadOnly,
   objSetProp,
@@ -927,6 +985,7 @@ export {
   search,
   sliceMap,
   sort,
+  strToArr,
   throttled,
   toDatetimeLocal
 };

package/package.json

@@ -36,10 +36,11 @@
 		"_watch": "tsc -p tsconfig.json --watch",
 		"build": "tsup src/index.ts --format esm --dts --clean --config ../../tsup.config.js",
 		"dev": "npm run build -- --watch",
-		"test": "cd ../../ && npm run test promise"
+		"start": "npm run build -- --watch",
+		"test": "cd ../../ && npm run test core"
 	},
 	"sideEffects": false,
 	"type": "module",
 	"types": "dist/index.d.ts",
-	"version": "1.0.4"
+	"version": "1.0.6"
 }