@superutils/core 1.1.4 → 1.1.6

package/README.md

@@ -13,11 +13,16 @@ For full API reference check out the [docs page](https://alien45.github.io/super
 - [Installation](#installation)
 - [Usage](#usage)
     - [`is`](#is): Type checkers
-    - [`deferred()`](#deferred): Debounce callbacks
+    - [`debounce()`](#debounce): Debounce callbacks
     - [`throttle()`](#throttle): Throttle callbacks
+    - [`deferred()`](#deferred): Debounce/Throttle callbacks
     - [`fallbackIfFails()`](#fallback-if-fails): Gracefully invoke functions or promises with a fallback
     - [`objCopy()`](#obj-copy): Deep-copy objects
     - [`search()`](#search): Search iterable collections
+        - [Advanced search options](#search-advanced)
+        - [`Ranked search`](#search-ranked): sort results by relevance
+        - [Combine `search()` with `deferred()`](#search-deferred): simulate a search input with debounce mechanism
+    - [`curry()`](#curry): Convert any function into a curried function
 
 ## Installation
 
@@ -72,27 +77,29 @@ import {
 } from '@superutils/core'
 ```
 
-<div id="deferred"></div>
-
-### `deferred(fn)`: debounce callbacks
+<div id="debouce"></div>
 
-`debounce()`, a sugar for `deferred()`, is also available.
+### `debouce(fn, delay, options)`: debounce callbacks
 
 ```javascript
-import { deferred } from '@superutils/core'
+import { debouce } from '@superutils/core'
 
-const handleChange = deferred(
+const handleChange = debouce(
 	event => console.log(event.target.value),
 	300, // debounce delay in milliseconds
+	{
+		leading: false, // default
+	},
 )
-handleChange({ target: { value: 1 } }) // will be ignored
+handleChange({ target: { value: 1 } }) // will be ignored, unless `leading = true`
 handleChange({ target: { value: 2 } }) // will be ignored
-handleChange({ target: { value: 3 } }) // will be executed
+handleChange({ target: { value: 3 } }) // will be ignored
+handleChange({ target: { value: 4 } }) // will be executed
 ```
 
 <div id="throttle"></div>
 
-### `throttle(fn)`: throttle callbacks
+### `throttle(fn, delay, options)`: throttle callbacks
 
 ```javascript
 import { throttle } from '@superutils/core'
@@ -100,10 +107,33 @@ import { throttle } from '@superutils/core'
 const handleChange = throttle(
 	event => console.log(event.target.value),
 	300, // throttle duration in milliseconds
+	{
+		trailing: false, // default
+	},
 )
 handleChange({ target: { value: 1 } }) // will be executed
 handleChange({ target: { value: 2 } }) // will be ignored
 handleChange({ target: { value: 3 } }) // will be ignored
+handleChange({ target: { value: 4 } }) // will be ignored, unless `trailing = true`
+```
+
+<div id="deferred"></div>
+
+### `deferred(fn, delay, options)`: debounce/throttle callbacks
+
+Create debounced/throttled functions using the `throttle` switch.
+
+```javascript
+import { deferred } from '@superutils/core'
+
+const handleChange = deferred(
+	event => console.log(event.target.value),
+	300, // delay in milliseconds
+	{ throttle: false }, // determines whether to create a debounced or throttled function
+)
+handleChange({ target: { value: 1 } }) // will be ignored
+handleChange({ target: { value: 2 } }) // will be ignored
+handleChange({ target: { value: 3 } }) // will be executed
 ```
 
 <div id="fallback-if-fails"></div>
@@ -236,6 +266,8 @@ search(data, { query: /li/i }) // Using regular expression
 // ])
 ```
 
+<div id="search-advanced"></div>
+
 #### Advanced Search Options:
 
 ```javascript
@@ -275,3 +307,96 @@ search(data, {
 //   { age: 28, name: 'Dave' }
 // ]
 ```
+
+<div id="search-ranked"></div>
+
+#### Search Ranked: sort results by relevance
+
+When `ranked` is set to `true`, results are sorted by relevance. In this example, "Alice" is ranked higher than "Charlie" because the match "li" appears earlier in the string.
+
+```javascript
+import { search } from '@superutils/core'
+
+// Sample colletion
+const data = new Map([
+	[2, { age: 25, name: 'Bob' }],
+	[3, { age: 35, name: 'Charlie' }],
+	[4, { age: 28, name: 'Dave' }],
+	[5, { age: 22, name: 'Eve' }],
+	[1, { age: 30, name: 'Alice' }],
+])
+const result = search(data, {
+	asMap: false, // Result type: true => Map (default, keys preserved), false => Array
+	limit: 10, // Number of items returned. Default: no limit
+	query: /li/i,
+	ranked: true,
+})
+console.log(result)
+// [ { age: 30, name: 'Alice' }, { age: 35, name: 'Charlie' } ]
+```
+
+<div id="search-deferred"></div>
+
+#### Combine `search()` with `deferred()`: simulate a search input with debounce mechanism
+
+```javascript
+import { deferred, search } from '@superutils/core'
+
+// sample colletion
+const data = new Map([
+	[1, { age: 30, name: 'Alice' }],
+	[2, { age: 25, name: 'Bob' }],
+	[3, { age: 35, name: 'Charlie' }],
+	[4, { age: 28, name: 'Dave' }],
+	[5, { age: 22, name: 'Eve' }],
+])
+
+const searchDeferred = deferred(
+	event => {
+		const result = search(data, {
+			query: {
+				name: new RegExp(event?.target?.value, 'i'),
+			},
+		})
+		// print result to console
+		console.log(result)
+	},
+	300, // debounce duration in milliseconds
+	{ leading: false }, // optional defer options
+)
+
+// ignored
+searchDeferred({ target: { value: 'l' } })
+// ignored
+setTimeout(() => searchDeferred({ target: { value: 'li' } }), 50)
+// executed: prints `Map(1) { 3 => { age: 35, name: 'Charlie' } }`
+setTimeout(() => searchDeferred({ target: { value: 'lie' } }), 200)
+// executed: prints `Map(1) { 1 => { age: 30, name: 'Alice' } }`
+setTimeout(() => searchDeferred({ target: { value: 'lic' } }), 510)
+```
+
+<div id="curry"></div>
+
+### `curry(fn, arity)`: Convert any function into a curried function
+
+```typescript
+const func = (
+	first: string,
+	second: number,
+	third?: boolean,
+	fourth?: string,
+) => `${first}-${second}-${third}-${fourth}`
+// We create a new function from the `func()` function that acts like a type-safe curry function
+// while also being flexible with the number of arguments supplied.
+const curriedFunc = curry(func)
+
+// Example 1: usage like a regular curry function and provide one argument at a time.
+// Returns a function expecting args: second, third, fourth
+const fnWith1 = curriedFunc('first')
+// Returns a function expecting args: third, fourth
+const fnWith2 = fnWith1(2)
+// returns a function epecting only fourth arg
+const fnWith3 = fnWith2(false)
+// All args are now provided, the original function is called and result is returned.
+const result = fnWith3('last')
+```

package/dist/index.d.ts

@@ -28,15 +28,6 @@ type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc e
     ...KeepRequired<TArgs>,
     ...KeepOptionals<TArgs, true, undefined>
 ], TArity>;
-/**
- * Deferred function options
- */
-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
  * ---
@@ -67,6 +58,13 @@ type DropFirstN<T extends unknown[], N extends number, Dropped extends unknown[]
  * ```
  */
 type DropLast<T extends unknown[]> = T extends [...infer Rest, unknown] ? Rest : [];
+/**
+ * If `T` is a promise turn it into an union type by adding the value type
+ */
+type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
+/**
+ * Check if a tuple/array has a finite length
+ */
 type IsFiniteTuple<T extends unknown[]> = number extends T['length'] ? false : true;
 type IsOptional<T, K extends keyof T> = {} extends Pick<T, K> ? true : false;
 /**
@@ -188,7 +186,10 @@ type TupleWithAlt<Tuple extends unknown[], TAlt = undefined> = {
  * ```
  */
 type ValueOrFunc<Value, Args extends unknown[] = []> = Value | ((...args: Args) => Value);
-/** Accept value a promise resolving to value */
+/**
+ * Represents a value that can be either a direct value of type `T` or a `Promise` that resolves to `T`.
+ * This is useful for functions that can handle both synchronous and asynchronous results.
+ */
 type ValueOrPromise<T> = T | Promise<T>;
 
 /**
@@ -254,80 +255,20 @@ declare function curry<TData, TArgs extends unknown[], TArgsIsFinite extends boo
     arity: TArity
 ]): Curry<TData, CurriedArgs<TArgs, TArgsIsFinite, (...args: TArgs) => TData, TArity>>;
 
-/**
- *
- * Returns a function that invokes the callback function after certain delay/timeout.
- * All errors will be gracefully swallowed.
- *
- * @param	callback 	function to be invoked after timeout
- * @param	delay		(optional) timeout duration in milliseconds. Default: 50
- * @param   config.onError (optional)
- * @param   config.leading (optional) if true, will enable leading-edge debounce mechanism.
- * @param   config.thisArg (optional) the special `thisArgs` to be used when invoking the callback.
- * @param	config.tid	   (optional) Timeout Id. If provided, will clear the timeout on first invocation.
- *
- * @example Debounce function calls
- * ```javascript
- * import { deferred } from '@superutils/core'
- *
- * const handleChange = deferred(
- *     event => console.log('Value:', event.target.value),
- *     300 // debounce delay in milliseconds
- * )
- *
- * handleChange({ target: { value: 1 } }) // will be ignored
- * handleChange({ target: { value: 2 } }) // will be ingored
- * handleChange({ target: { value: 3 } }) // will be invoked
- * ```
- */
-declare const deferred: {
-    <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.
-         * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
-         */
-        leading: false;
-        /**
-         * Set the default value of argument `onError` for the `deferred` function.
-         * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
-         */
-        onError: undefined;
-    };
-};
-
-/** Super for `deferred()` function */
-declare const debounce: {
-    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: DeferredOptions<ThisArg>): (...args: TArgs) => void;
-    defaults: {
-        leading: false;
-        onError: undefined;
-    };
-};
-
-/**
- * If `T` is a promise turn it into an union type by adding the value type
- */
-type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
 /**
  * @function fallbackIfFails
  * @summary a flexible try-catch wrapper for invoking functions and ignore errors gracefully.
  * Yes, the goal of `fallbackIfFails` is to ignore all runtime errors
  * and ensure there's always a value returned.
  *
- * ---
- *
- * `fallbackValue` PS:
+ * @param target promise or function to execute
+ * @param args arguments to be supplied to `func` fuction
+ * @param fallback alternative value to be used when target throws error.
  *
- * 1. If function provided and Error is thrown it will not be caught.
- * A fallback of the fallback is out of the scope of this function.
- * 2. If `target` a promise or async function, `fallbackValue` must either be a promise or resolve to a promise
- *
- * ---
- *
- * @param target        promise or function to execute
- * @param args			arguments to be supplied to `func` fuction
- * @param fallbackValue alternative value to be used when target throws error.
+ * - If `fallback` is a function and it raises exception, it will cause to raise an exception instead of gracefully
+ * ignoring it. A fallback of the fallback function is out of the scope of `fallbackIfFails`. However, the fallback
+ * function can still be wrapped inside a secondary `fallbackIfFails`. See the "Fallback chaining" example below.
+ * - If `target` a promise or async function, `fallback` can be either be  a value, a promise or an async function.
  *
  * @returns if func is a promise the return a promise
  *
@@ -335,7 +276,10 @@ type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
  * ---
  * @example Async functions
  * Working with async functions or functions that returns a promise
+ *
  * ```typescript
+ * import { fallbackIfFails } from '@superutils/core'
+ *
  * const args = ['some value', true] as const
  * const ensureValue = async (value: string, criteria?: boolean) => {
  *     if (criteria !== false && !value.trim()) throw new Error('No value. Should use fallback value')
@@ -351,7 +295,10 @@ type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
  *
  * @example Non-async functions
  * Working synchronous function that returns value synchronously
+ *
  * ```typescript
+ * import { fallbackIfFails } from '@superutils/core'
+ *
  * const args = ['some value', true] as const
  * const ensureValue = (value: string, criteria?: boolean) => {
  *     if (criteria !== false && !value.trim()) throw new Error('No value. Should use fallback value')
@@ -367,7 +314,10 @@ type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
  *
  * @example Hybrid functions
  * Working with function that returns value sync/async circumstantially
+ *
  * ```typescript
+ * import { fallbackIfFails } from '@superutils/core'
+ *
  * const getData = (useCache = true, cacheKey = 'data-cache') => {
  *     if (useCache && localStorage[cacheKey]) return localStorage[cacheKey]
  *     return fetch('https://my.domain.com/api')
@@ -382,8 +332,29 @@ type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
  * // Second call: cache available and will return data synchronously
  * const second = fallbackIfFails(getData, [true], {})
  * ```
+ *
+ * @example Fallback-chaining: gracefully handle the fallback function
+ *
+ * ```typescript
+ * import { fallbackIfFails } from '@superutils/core'
+ *
+ * const target = () => {
+ *     if (new Date().getTime() > 0) throw new Error('I will raise error')
+ * }
+ * const fallback = () => {
+ *     throw new Error('I will also raise an exception')
+ * }
+ * const value = fallbackIfFails(
+ *     target,
+ *     [],
+ * 	   // this function will only be invoked when
+ *     () => fallbackIfFails(fallback, [], undefined)
+ * )
+ *
+ * console.log({ value }) // undefined
+ * ```
  */
-declare const fallbackIfFails: <T, TArgs extends unknown[] = unknown[]>(target: T | ((...args: TArgs) => T), args: TArgs | (() => TArgs), fallbackValue: IfPromiseAddValue<T> | ((reason: unknown) => IfPromiseAddValue<T>)) => T;
+declare const fallbackIfFails: <T, TArgs extends unknown[] = unknown[]>(target: T | ((...args: TArgs) => T), args: TArgs | (() => TArgs), fallback: IfPromiseAddValue<T> | ((reason: unknown) => IfPromiseAddValue<T>)) => T;
 
 /** Check if value is an array */
 declare const isArr: <Item = unknown>(x: unknown) => x is Item[];
@@ -514,12 +485,16 @@ declare const isMapObj: <K extends PropertyKey, V, T extends Record<K, V>>(x: un
 
 /** Check if value is an integer */
 declare const isInteger: (x: unknown) => x is number;
+/** Check if value is a valid negative integer */
+declare const isNegativeInteger: (x: unknown) => x is number;
+/** Check if value is a valid negative number */
+declare const isNegativeNumber: (x: unknown) => x is number;
+/** Check if value is a valid finite number */
+declare const isNumber: (x: unknown) => x is number;
 /** Check if value is a positive integer */
 declare const isPositiveInteger: (x: unknown) => x is number;
 /** Check if value is a positive number */
 declare const isPositiveNumber: (x: unknown) => x is number;
-/** Check if value is a valid finite number */
-declare const isNumber: (x: unknown) => x is number;
 
 /**
  * Check if value is an object.
@@ -598,6 +573,15 @@ declare const isRegExp: (x: unknown) => x is RegExp;
 declare const isSet: <T = unknown>(x: unknown) => x is Set<T>;
 /** Check if value is string */
 declare const isStr: (x: unknown) => x is string;
+/**
+ * Check if value is similar to a RxJS subject with .subscribe & .next functions
+ *
+ * @param x The value to check
+ * @param withValue When `true`, also checks if `value` property exists in `x`
+ *
+ * @returns `true` if the value is subject-like, `false` otherwise.
+ */
+declare const isSubjectLike: <T>(x: unknown, withValue?: boolean) => boolean;
 /** Check if value is a Symbol */
 declare const isSymbol: (x: unknown) => x is symbol;
 /**
@@ -625,6 +609,8 @@ declare const is: {
     integer: (x: unknown) => x is number;
     map: <TKey = unknown, TValue = unknown>(x: unknown) => x is Map<TKey, TValue>;
     mapObj: <K extends PropertyKey, V, T extends Record<K, V>>(x: unknown, strict?: boolean) => x is Map<K, V>;
+    negativeInteger: (x: unknown) => x is number;
+    negativeNumber: (x: unknown) => x is number;
     number: (x: unknown) => x is number;
     obj: <T = Record<PropertyKey, unknown>>(x: unknown, strict?: boolean) => x is T;
     positiveInteger: (x: unknown) => x is number;
@@ -633,6 +619,7 @@ declare const is: {
     regExp: (x: unknown) => x is RegExp;
     set: <T = unknown>(x: unknown) => x is Set<T>;
     str: (x: unknown) => x is string;
+    subjectLike: <T>(x: unknown, withValue?: boolean) => boolean;
     symbol: (x: unknown) => x is symbol;
     uint8Arr: (arr: unknown) => arr is Uint8Array<ArrayBufferLike>;
     url: (x: unknown) => x is URL;
@@ -643,48 +630,6 @@ declare const is: {
 declare function noop(): void;
 declare function noopAsync(): Promise<void>;
 
-type ThrottleOptions<ThisArg = unknown> = {
-    onError?: (err: unknown) => ValueOrPromise<unknown>;
-    thisArg?: ThisArg;
-    trailing?: boolean;
-    tid?: TimeoutId;
-};
-/**
- * @function throttle
- * @summary returns a function that invokes the `callback` maximum twice (once if `executeLast = false`) per interval
- *
- * @param	callback function to be invoked after timeout
- * @param	delay	 (optional) interval duration in milliseconds. Default: 50
- * @param   config.onError  (optional)
- * @param   config.tid      (optional)
- * @param	config.thisArg  (optional) the special `thisArgs` to be used when invoking the callback.
- * @param   config.trailing (optional) whether to enable trailing edge execution. Default: `true`
- *
- * @example
- * ```javascript
- * import { throttle } from '@superutils/core'
- *
- * const handleChange = throttle(
- *     event => console.log('Value:', event.target.value),
- *     300, // throttle duration in milliseconds
- * )
- * handleChange({ target: { value: 1 } }) // will be executed
- * handleChange({ target: { value: 2 } }) // will be ignored
- * handleChange({ target: { value: 3 } }) // will be ignored
- * ```
- */
-declare const throttled: {
-    <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()`.
-     */
-    defaults: {
-        onError: undefined;
-        trailing: false;
-    };
-};
-
 /**
  * Convert timestamp to `input["datetime-local"]` compatible format.
  *
@@ -841,8 +786,7 @@ declare const objSetPropUndefined: (...[obj, key, ...args]: Parameters<typeof ob
 declare const objSort: <T>(obj: T, recursive?: boolean, _done?: Map<unknown, boolean>) => T;
 
 /**
- * @function	objWithoutKeys
- * @summary constructs a new object excluding specific properties
+ * Creates a new object excluding specific properties
  *
  * @param	{Object}	input
  * @param	{Array}		keys	property names to exclude
@@ -850,6 +794,27 @@ declare const objSort: <T>(obj: T, recursive?: boolean, _done?: Map<unknown, boo
  * 								Default: a copy of the `input` object
  *
  * @returns {Object}
+ *
+ * @example Create a new object excluding specific properties
+ *
+ * ```javascript
+ * import { objWithoutKeys } from '@superutils/core'
+ *
+ * const result = objWithoutKeys({ a: 1, b: '2', c: false }, ['b', 'c'])
+ * console.log(result) // { a: 1 }
+ * ```
+ *
+ * @example Copy one object's properties to another while ignoring specific properties
+ *
+ * ```javascript
+ * import { objWithoutKeys } from '@superutils/core'
+ *
+ * const source = { a: 1, b: '2', c: false }
+ * const dest = { d: 4, e: 5 }
+ * const result = objWithoutKeys(source, ['b', 'c'], dest)
+ * console.log(result) // { d: 4, e: 5, a: 1 }
+ * console.log(result === dest) // true
+ * ```
  */
 declare const objWithoutKeys: (input: unknown, keys: string[], output?: Record<PropertyKey, unknown>) => Record<PropertyKey, unknown>;
 
@@ -913,6 +878,7 @@ declare const arrReverse: <T = unknown>(arr: T[], reverse?: boolean, newArray?:
  * 	   arr,
  * 	   (_: Item, i: number) => item.a,
  * )
+ * ```
  *
  * @example Flatten and convert Array to Map
  * ```typescript
@@ -936,6 +902,173 @@ declare function arrToMap<T extends unknown[], FlatDepth extends number = 0, Map
  */
 declare const arrUnique: <T = unknown>(arr: T[], flatDepth?: number) => FlatArray<T, 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | -1 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20>[];
 
+/**
+ * Debounce function options
+ */
+type DebounceOptions<ThisArg = unknown> = {
+    leading?: boolean | 'global';
+    onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
+    thisArg?: ThisArg;
+    tid?: TimeoutId;
+};
+/**
+ * Deferred function options
+ */
+type DeferredOptions<ThisArg = unknown> = ({
+    throttle: true;
+} & ThrottleOptions<ThisArg>) | ({
+    throttle?: false;
+} & DebounceOptions<ThisArg>);
+/**
+ * Throttle function options
+ */
+type ThrottleOptions<ThisArg = unknown> = {
+    /**
+     *
+     * @param err Error object thrown by the callback function.
+     * @returns
+     */
+    onError?: (this: ThisArg, err: unknown) => ValueOrPromise<unknown>;
+    thisArg?: ThisArg;
+    trailing?: boolean;
+    tid?: TimeoutId;
+};
+
+/**
+ * Returns a function that invokes the callback function after certain delay/timeout.
+ * All errors will be gracefully swallowed.
+ *
+ * @param	callback 	function to be invoked after timeout
+ * @param	delay		(optional) timeout duration in milliseconds. Default: 50
+ * @param   config.onError (optional)
+ * @param   config.leading (optional) if true, will enable leading-edge debounce mechanism.
+ * @param   config.thisArg (optional) the special `thisArgs` to be used when invoking the callback.
+ * @param	config.tid	   (optional) Timeout Id. If provided, will clear the timeout on first invocation.
+ *
+ * @example Debounce function calls
+ * ```javascript
+ * import { deferred } from '@superutils/core'
+ *
+ * const handleChange = deferred(
+ *     event => console.log('Value:', event.target.value),
+ *     300 // debounce delay in milliseconds
+ * )
+ *
+ * handleChange({ target: { value: 1 } }) // will be ignored
+ * handleChange({ target: { value: 2 } }) // will be ingored
+ * handleChange({ target: { value: 3 } }) // will be invoked
+ * ```
+ */
+declare const debounce: {
+    <TArgs extends unknown[], ThisArg>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: number, config?: DebounceOptions<ThisArg>): (...args: TArgs) => void;
+    defaults: {
+        /**
+         * Set the default value of argument `leading` for the `deferred` function.
+         * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
+         */
+        leading: false;
+        /**
+         * Set the default value of argument `onError` for the `deferred` function.
+         * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
+         */
+        onError: undefined;
+    };
+};
+
+/**
+ * Returns a function that can be used to debounce/throttle calls to the provided callback function.
+ * All errors will be gracefully swallowed. See {@link debounce} and {@link throttle} for more information.
+ *
+ * @param callback function to be invoked after delay
+ * @param delay (optional) delay duration in milliseconds. Default: `50`
+ * @param config (optional) debounce or throttle configuration options
+ *
+ * @returns Callback function that can be invoked in one of the following 2 methods:
+ * - debounced: when `throttle` is `false` or `undefined`
+ * - throttled: when `throttle` is `true`
+ */
+declare const deferred: <TArgs extends unknown[], ThisArg, Delay = unknown>(callback: (this: ThisArg, ...args: TArgs) => ValueOrPromise<unknown>, delay?: Delay, config?: DeferredOptions<ThisArg>) => (...args: TArgs) => void;
+
+/**
+ * Returns a throttled function that ensures the callback is invoked at most once in the specified delay interval.
+ * All errors will be gracefully swallowed.
+ *
+ * If the throttled function is called multiple times during the delay interval, only the first call will invoke the callback immediately.
+ *
+ * If `trailing` is enabled and if returned function is invoked more than once during the delay interval,
+ * the callback runs again at the end of the delay with the most recent arguments.
+ *
+ * @param callback function to be invoked after timeout
+ * @param delay (optional) interval duration in milliseconds. Default: 50
+ * @param config (optional)
+ * @param config.onError (optional) callback to be invoked on error
+ * @param config.tid (optional)
+ * @param config.thisArg (optional) the special `thisArgs` to be used when invoking the callback.
+ * @param config.trailing (optional) whether to enable trailing edge execution. Default: `true`
+ *
+ * @example Throttle function calls
+ * ```javascript
+ * import { throttle } from '@superutils/core'
+ *
+ * const handleChange = throttle(
+ *     event => console.log('Value:', event.target.value),
+ *     300, // throttle duration in milliseconds
+ * )
+ * handleChange({ target: { value: 1 } }) // will be executed
+ * handleChange({ target: { value: 2 } }) // will be ignored
+ * handleChange({ target: { value: 3 } }) // will be ignored
+ *
+ * setTimeout(() => {
+ *    handleChange({ target: { value: 4 } }) // will be executed (after 300ms)
+ *    handleChange({ target: { value: 5 } }) // will be ignored
+ * }, 400)
+ * ```
+ *
+ * @example Throttle with trailing enabled
+ * ```javascript
+ * import { throttle } from '@superutils/core'
+ *
+ * const handleChange = throttle(
+ *     event => console.log('Value:', event.target.value),
+ *     300, // throttle duration in milliseconds
+ * )
+ * handleChange({ target: { value: 1 } }) // will be executed
+ * handleChange({ target: { value: 2 } }) // will be ignored
+ * handleChange({ target: { value: 3 } }) //  will be executed
+ *
+ * setTimeout(() => {
+ *    handleChange({ target: { value: 4 } }) // will be executed
+ *    handleChange({ target: { value: 5 } }) // will be ignored
+ * }, 400)
+ * ```
+ */
+declare const throttle: {
+    <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()`.
+     */
+    defaults: {
+        onError: undefined;
+        trailing: false;
+    };
+};
+/**
+ * For legacy compatibility
+ * @deprecated use `throttle` instead
+ */
+declare const throttled: {
+    <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()`.
+     */
+    defaults: {
+        onError: undefined;
+        trailing: false;
+    };
+};
+
 /** Configuration for finding {@link IterableList} items */
 type FindOptions<K, V, IncludeKey extends boolean = false> = Omit<SearchOptions<K, V>, 'limit' | 'asMap'> & {
     /**
@@ -1053,7 +1186,7 @@ declare const filter: <K, V, AsArray extends boolean = false, Result = AsArray e
  *
  * @returns first item matched or `undefined` if not found
  *
- * @example Find item using callback
+ * @example Find item using predicate callback
  * ```typescript
  * import { find } from '@superutils/core'
  *
@@ -1182,7 +1315,7 @@ type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
     start?: number;
 };
 /**
- * Slice an iterable list and map the values into an Array/Map
+ * Slice an iterable list and map the values into an Array/Map.
  *
  * @param data		Array, Map, Set...
  * @param options	One of the following is required to create a new list:
@@ -1202,6 +1335,27 @@ type SliceMapOptions<Data, Value, Key, AsMap extends boolean = false> = {
  *   - data: original list
  *
  * @returns Array/Map
+ *
+ * @example
+ * ```javascript
+ * const data = new Map([
+ * 	[0, { age: 30, name: 'Alice' }],
+ * 	[1, { age: 25, name: 'Bob' }],
+ * 	[2, undefined],
+ * 	[3, {}],
+ * 	[4, { age: 35, name: 'Charlie' }],
+ * 	[5, { age: 28, name: 'Dave' }],
+ * 	[6, { age: 22, name: 'Eve' }],
+ * ])
+ * const result = sliceMap(data, {
+ * 	asMap: false, // whether to return the result as a Map
+ * 	end: 5, // last index (exclusive)
+ * 	ignoreEmpty: true, // ignore items with no value
+ * 	start: 1, // first index
+ * })
+ * console.log(result)
+ * // [ { age: 25, name: 'Bob' }, { age: 35, name: 'Charlie' } ]
+ * ```
  */
 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;
 
@@ -1317,12 +1471,30 @@ 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 */
+/**
+ * Describes a valid finite number type.
+ */
+type FiniteNumber<N> = N extends number ? number extends N ? never : N : never;
+/**
+ * Describes an integer type.
+ */
+type Integer<N> = N extends number ? number extends N ? never : `${N}` extends `${string}.${string}` | `.${string}` | `${string}e-${string}` ? never : N : never;
+/**
+ * Describes a number type with negative integer values.
+ */
+type NegativeInteger<N> = N extends number ? `${N}` extends `-${string}` ? `${N}` extends `-${string}.${string}` | `-${string}e-${string}` ? never : N : never : never;
+/**
+ * Describes a number type with negative values.
+ */
 type NegativeNumber<N> = N extends number ? `${N}` extends `-${string}` ? N : never : never;
-/** Describes a number type with positive values excluding `0`  */
-type PositiveNumber<N> = N extends number ? `${N}` extends `-${string}` | '0' ? never : N : never;
-/** Describes a number type with positive values and `0`  */
-type PositiveNumberWithZero<N> = N extends number ? `${N}` extends `-${string}` ? never : N : never;
+/**
+ * Describes a number type with positive integer values.
+ */
+type PositiveInteger<N> = N extends number ? number extends N ? never : `${N}` extends `-${string}` | '0' | `${string}.${string}` | `${string}e-${string}` ? never : N : never;
+/**
+ * Describes a number type with positive values.
+ */
+type PositiveNumber<N> = N extends number ? number extends N ? never : `${N}` extends `-${string}` | '0' ? never : N : never;
 
 /**
  * Clears clutter from strings
@@ -1386,4 +1558,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, clearClutter, copyToClipboard, curry, debounce, deferred, fallbackIfFails, filter, find, 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 };
+export { type ArrayComparator, type AsyncFn, type CreateTuple, type CurriedArgs, type Curry, type DebounceOptions, type DeferredOptions, type DropFirst, type DropFirstN, type DropLast, EMAIL_REGEX, type EntryComparator, type FindOptions, type FiniteNumber, HASH_REGEX, HEX_REGEX, type IfPromiseAddValue, type Integer, type IsFiniteTuple, type IsOptional, type IterableList, type KeepFirst, type KeepFirstN, type KeepOptionals, type KeepRequired, type MakeOptional, type MinLength, type NegativeInteger, type NegativeNumber, type OptionalIf, type PositiveInteger, type PositiveNumber, 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, clearClutter, copyToClipboard, curry, debounce, deferred, fallbackIfFails, filter, find, 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, isNegativeInteger, isNegativeNumber, isNumber, isObj, isPositiveInteger, isPositiveNumber, isPromise, isRegExp, isSet, isStr, isSubjectLike, isSymbol, isUint8Arr, isUrl, isUrlValid, mapJoin, matchObjOrProp, noop, noopAsync, objClean, objCopy, objCreate, objHasKeys, objKeys, objReadOnly, objSetProp, objSetPropUndefined, objSort, objWithoutKeys, randomInt, reverse, search, sliceMap, sort, strToArr, throttle, throttled, toDatetimeLocal };

package/dist/index.js

@@ -48,9 +48,11 @@ var isDate_default = isDate;
 
 // src/is/isNumber.ts
 var isInteger = (x) => Number.isInteger(x);
+var isNegativeInteger = (x) => Number.isInteger(x) && x < 0;
+var isNegativeNumber = (x) => isNumber(x) && x < 0;
+var isNumber = (x) => typeof x === "number" && !Number.isNaN(x) && Number.isFinite(x);
 var isPositiveInteger = (x) => isInteger(x) && x > 0;
 var isPositiveNumber = (x) => isNumber(x) && x > 0;
-var isNumber = (x) => typeof x == "number" && !Number.isNaN(x) && Number.isFinite(x);
 
 // src/is/isEmpty.ts
 var isEmpty = (x, nonNumerable = false, fallback = false) => {
@@ -149,6 +151,7 @@ var isPromise = (x) => x instanceof Promise;
 var isRegExp = (x) => x instanceof RegExp;
 var isSet = (x) => x instanceof Set;
 var isStr = (x) => typeof x === "string";
+var isSubjectLike = (x, withValue = false) => isObj_default(x, false) && isFn_default(x.subscribe) && isFn_default(x.next) && (!withValue || "value" in x);
 var isSymbol = (x) => typeof x === "symbol";
 var is = {
   arr: isArr_default,
@@ -172,6 +175,8 @@ var is = {
   integer: isInteger,
   map: isMap,
   mapObj: isMapObj,
+  negativeInteger: isNegativeInteger,
+  negativeNumber: isNegativeNumber,
   number: isNumber,
   obj: isObj_default,
   positiveInteger: isPositiveInteger,
@@ -180,7 +185,7 @@ var is = {
   regExp: isRegExp,
   set: isSet,
   str: isStr,
-  // subjectLike: isSubjectLike,
+  subjectLike: isSubjectLike,
   symbol: isSymbol,
   uint8Arr: isUint8Arr,
   url: isUrl_default,
@@ -188,86 +193,18 @@ var is = {
 };
 
 // src/fallbackIfFails.ts
-var fallbackIfFails = (target, args, fallbackValue) => {
-  let result;
+var fallbackIfFails = (target, args, fallback) => {
   try {
-    result = !isFn(target) ? target : target(...isFn(args) ? args() : args);
+    const result = !isFn(target) ? target : target(...isFn(args) ? args() : args);
     if (!isPromise(result)) return result;
-    return result.catch((err) => getAltValCb(err, fallbackValue));
-  } catch (error) {
-    return getAltValCb(error, fallbackValue);
+    return result.catch(
+      (err) => isFn(fallback) ? fallback(err) : fallback
+    );
+  } catch (err) {
+    return isFn(fallback) ? fallback(err) : fallback;
   }
 };
 var fallbackIfFails_default = fallbackIfFails;
-var getAltValCb = (error, fallbackValue) => isFn(fallbackValue) ? fallbackValue(error) : fallbackValue;
-
-// src/deferred.ts
-var deferred = (callback, delay = 50, config = {}) => {
-  const {
-    leading = deferred.defaults.leading,
-    onError = deferred.defaults.onError,
-    thisArg
-  } = config;
-  let { tid } = config;
-  if (thisArg !== void 0) callback = callback.bind(thisArg);
-  const _callback = (...args) => fallbackIfFails_default(callback, args, onError);
-  let firstArgs = null;
-  const leadingGlobal = leading === "global";
-  return (...args) => {
-    clearTimeout(tid);
-    tid = setTimeout(() => {
-      firstArgs !== args && _callback(...args);
-      firstArgs = leadingGlobal ? true : null;
-    }, delay);
-    if (!leading || firstArgs) return;
-    firstArgs = args;
-    _callback(...args);
-  };
-};
-deferred.defaults = {
-  /**
-   * Set the default value of argument `leading` for the `deferred` function.
-   * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
-   */
-  leading: false,
-  /**
-   * Set the default value of argument `onError` for the `deferred` function.
-   * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
-   */
-  onError: void 0
-};
-var deferred_default = deferred;
-
-// src/debounce.ts
-var debounce = deferred_default;
-
-// src/throttled.ts
-var throttled = (callback, delay = 50, config = {}) => {
-  const { defaults: d } = throttled;
-  const { onError = d.onError, trailing = d.trailing, thisArg } = config;
-  let { tid } = config;
-  if (thisArg !== void 0) callback = callback.bind(thisArg);
-  const _callback = (...args) => fallbackIfFails_default(callback, args, onError);
-  let trailArgs = null;
-  return (...args) => {
-    if (tid) {
-      trailArgs = args;
-      return;
-    }
-    tid = setTimeout(() => {
-      tid = void 0;
-      if (!trailing) return;
-      const cbArgs = trailArgs;
-      trailArgs = null;
-      cbArgs && cbArgs !== args && _callback(...cbArgs);
-    }, delay);
-    _callback(...args);
-  };
-};
-throttled.defaults = {
-  onError: void 0,
-  trailing: false
-};
 
 // src/toDatetimeLocal.ts
 var toDatetimeLocal = (dateStr) => {
@@ -533,6 +470,79 @@ function arrToMap(arr, key, flatDepth = 0) {
 // src/arr/arrUnique.ts
 var arrUnique = (arr, flatDepth = 0) => !isArr(arr) ? [] : Array.from(new Set(arr.flat(flatDepth)));
 
+// src/deferred/debounce.ts
+var debounce = (callback, delay = 50, config = {}) => {
+  const {
+    leading = debounce.defaults.leading,
+    onError = debounce.defaults.onError,
+    thisArg
+  } = config;
+  let { tid } = config;
+  if (thisArg !== void 0) callback = callback.bind(thisArg);
+  const _callback = (...args) => fallbackIfFails_default(callback, args, onError);
+  let firstArgs = null;
+  const leadingGlobal = leading === "global";
+  return (...args) => {
+    clearTimeout(tid);
+    tid = setTimeout(() => {
+      firstArgs !== args && _callback(...args);
+      firstArgs = leadingGlobal ? true : null;
+    }, delay);
+    if (!leading || firstArgs) return;
+    firstArgs = args;
+    _callback(...args);
+  };
+};
+debounce.defaults = {
+  /**
+   * Set the default value of argument `leading` for the `deferred` function.
+   * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
+   */
+  leading: false,
+  /**
+   * Set the default value of argument `onError` for the `deferred` function.
+   * This change is applicable application-wide and only applies to any new invocation of `deferred()`.
+   */
+  onError: void 0
+};
+var debounce_default = debounce;
+
+// src/deferred/throttle.ts
+var throttle = (callback, delay = 50, config = {}) => {
+  const { defaults: d } = throttle;
+  const { onError = d.onError, trailing = d.trailing, thisArg } = config;
+  let { tid } = config;
+  const handleCallback = (...args) => fallbackIfFails_default(
+    thisArg !== void 0 ? callback.bind(thisArg) : callback,
+    args,
+    !isFn(onError) ? void 0 : (err) => fallbackIfFails_default(onError, [err], void 0)
+  );
+  let trailArgs = null;
+  return (...args) => {
+    if (tid) {
+      trailArgs = args;
+      return;
+    }
+    tid = setTimeout(() => {
+      tid = void 0;
+      if (!trailing) return;
+      const cbArgs = trailArgs;
+      trailArgs = null;
+      cbArgs && cbArgs !== args && handleCallback(...cbArgs);
+    }, delay);
+    handleCallback(...args);
+  };
+};
+throttle.defaults = {
+  onError: void 0,
+  trailing: false
+};
+var throttled = throttle;
+var throttle_default = throttle;
+
+// src/deferred/deferred.ts
+var deferred = (callback, delay = 50, config = {}) => config.throttle ? throttle_default(callback, delay, config) : debounce_default(callback, delay, config);
+
 // src/iterable/filter.ts
 var filter = (data, predicate, limit, asArray, result) => {
   var _a;
@@ -673,7 +683,7 @@ function matchObjOrProp({
     ""
   );
   if (value === keyword) return 0;
-  if (matchExact) return -1;
+  if (matchExact && !isRegExp(keyword)) 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;
@@ -947,6 +957,8 @@ export {
   isInteger,
   isMap,
   isMapObj,
+  isNegativeInteger,
+  isNegativeNumber,
   isNumber,
   isObj,
   isPositiveInteger,
@@ -955,6 +967,7 @@ export {
   isRegExp,
   isSet,
   isStr,
+  isSubjectLike,
   isSymbol,
   isUint8Arr,
   isUrl,
@@ -979,6 +992,7 @@ export {
   sliceMap,
   sort,
   strToArr,
+  throttle,
   throttled,
   toDatetimeLocal
 };

package/package.json

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