@superutils/core 1.1.4 → 1.1.5

package/README.md

@@ -18,6 +18,10 @@ For full API reference check out the [docs page](https://alien45.github.io/super
     - [`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
 
@@ -236,6 +240,8 @@ search(data, { query: /li/i }) // Using regular expression
 // ])
 ```
 
+<div id="search-advanced"></div>
+
 #### Advanced Search Options:
 
 ```javascript
@@ -275,3 +281,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

@@ -315,19 +315,14 @@ type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
  * 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 +330,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 +349,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 +368,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 +386,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 +539,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 +627,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 +663,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 +673,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;
@@ -841,8 +882,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 +890,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>;
 
@@ -1182,7 +1243,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 +1263,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 +1399,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 +1486,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 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, 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,18 +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 = {}) => {
@@ -673,10 +678,11 @@ 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;
+  if (matchExact) return -1;
   if (ignoreCase) valueStr = valueStr.toLowerCase();
   return valueStr.indexOf(String(keyword));
 }
@@ -947,6 +953,8 @@ export {
   isInteger,
   isMap,
   isMapObj,
+  isNegativeInteger,
+  isNegativeNumber,
   isNumber,
   isObj,
   isPositiveInteger,
@@ -955,6 +963,7 @@ export {
   isRegExp,
   isSet,
   isStr,
+  isSubjectLike,
   isSymbol,
   isUint8Arr,
   isUrl,

package/package.json

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