@superutils/core 1.0.6 → 1.1.0

package/README.md

@@ -15,7 +15,7 @@ For full API reference check out the [docs page](https://alien45.github.io/super
     - [`is`](#is): Type checkers
     - [`deferred()`](#deferred): Debounce callbacks
     - [`throttle()`](#throttle): Throttle callbacks
-    - [`fallbackIfFails()`](#fallback-if-fails): Gracefully invoke functions
+    - [`fallbackIfFails()`](#fallback-if-fails): Gracefully invoke functions or promises with a fallback
     - [`objCopy()`](#obj-copy): Deep-copy objects
     - [`search()`](#search): Search iterable collections
 
@@ -53,8 +53,7 @@ is.map(new Map()) // true
 is.number(123) // true
 is.number(NaN) // false
 is.url('https://google.com') // true
-...
-
+//...
 ```
 
 All these functions can also be imported independantly.
@@ -80,16 +79,15 @@ import {
 `debounce()`, a sugar for `deferred()`, is also available.
 
 ```javascript
-
 import { deferred } from '@superutils/core'
 
 const handleChange = deferred(
-    event => console.log(event.target.value),
-    300 // debounce delay in milliseconds
+	event => console.log(event.target.value),
+	300, // debounce delay in milliseconds
 )
-handleChange({ target: { value 1 } }) // will be ignored
-handleChange({ target: { value 2 } }) // will be ignored
-handleChange({ target: { value 3 } }) // will be executed
+handleChange({ target: { value: 1 } }) // will be ignored
+handleChange({ target: { value: 2 } }) // will be ignored
+handleChange({ target: { value: 3 } }) // will be executed
 ```
 
 <div id="throttle"></div>
@@ -100,19 +98,19 @@ handleChange({ target: { value 3 } }) // will be executed
 import { throttle } from '@superutils/core'
 
 const handleChange = throttle(
-    event => console.log(event.target.value),
-    300 // throttle duration in milliseconds
+	event => console.log(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
+handleChange({ target: { value: 1 } }) // will be executed
+handleChange({ target: { value: 2 } }) // will be ignored
+handleChange({ target: { value: 3 } }) // will be ignored
 ```
 
 <div id="fallback-if-fails"></div>
 
-### `fallbackIfFails(fn, args, fallback)`: gracefully invoke functions
+### `fallbackIfFails(target, args, fallback)`: Gracefully invoke functions or promises with a fallback
 
-Based on the function provided `fallbackIfFails` will either execute synchronously or asynchronously.
+The `fallbackIfFails` function can wrap a standard function, a promise-returning function, or a promise directly. It automatically handles both synchronous execution and asynchronous resolution, providing a fallback value if the function throws an error or the promise is rejected.
 
 #### Sync operations:
 
@@ -149,6 +147,12 @@ fallbackIfFails(
 	{ products: [] }, // Fallback value to be returned when function throws an error.
 ).then(console.log)
 // Prints the result when request is successful or fallback value when request fails
+
+// use a promise
+fallbackIfFails(
+	Promise.reject('error'),
+	[], //
+)
 ```
 
 <div id="obj-copy"></div>
@@ -249,7 +253,7 @@ search(data, {
 	asMap: false, // Result type: true => Map (default, keys preserved), false => Array
 	ignoreCase: false, // For text case-sensitivity
 	limit: 10, // Number of items returned. Default: no limit
-	matchExact: true, // true: full text search. false (default): partial matching
+	matchExact: true, // true: match exact value. false (default): partial matching
 	matchAll: true, // if true, item will be matched only when all of the query properties match
 	query: {
 		age: /(2[5-9])|(3[0-5])/, // match ages 25-35

package/dist/index.d.ts

@@ -24,15 +24,19 @@ type CreateTuple<T, Length extends number, Output extends readonly unknown[] = [
  * @template TData The final return type.
  */
 type Curry<TData, TParams extends unknown[]> = <TArgs extends unknown[]>(...args: TArgs & KeepFirstN<TParams, TArgs['length']>) => DropFirstN<TParams, TArgs['length']> extends [unknown, ...unknown[]] ? Curry<TData, DropFirstN<TParams, TArgs['length']>> : TData;
+type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc extends (...args: any[]) => unknown, TArity extends number> = TArgsIsFinite extends false ? CreateTuple<Parameters<TFunc>[number], TArity> : KeepFirstN<[
+    ...KeepRequired<TArgs>,
+    ...KeepOptionals<TArgs, true, undefined>
+], TArity>;
 /**
- * Deferred function config
+ * Deferred function options
  */
-interface DeferredOptions<ThisArg = unknown> {
+type DeferredOptions<ThisArg = unknown> = {
     leading?: boolean | 'global';
     onError?: (err: unknown) => ValueOrPromise<unknown>;
     thisArg?: ThisArg;
     tid?: TimeoutId;
-}
+};
 /**
  * Drop the first item from an array/tuple and keep the rest
  * ---
@@ -249,14 +253,10 @@ type ValueOrPromise<T> = T | Promise<T>;
 declare function curry<TData, TArgs extends unknown[], TArgsIsFinite extends boolean = IsFiniteTuple<TArgs>, TArity extends TArgs['length'] = TArgsIsFinite extends true ? TupleMaxLength<TArgs> : number>(func: (...args: TArgs) => TData, ...[arity]: TArgsIsFinite extends true ? [arity?: TArity] : [
     arity: TArity
 ]): Curry<TData, CurriedArgs<TArgs, TArgsIsFinite, (...args: TArgs) => TData, TArity>>;
-type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc extends (...args: any[]) => unknown, TArity extends number> = TArgsIsFinite extends false ? CreateTuple<Parameters<TFunc>[number], TArity> : KeepFirstN<[
-    ...KeepRequired<TArgs>,
-    ...KeepOptionals<TArgs, true, undefined>
-], TArity>;
 
 /**
- * @function deferred AKA debounce
- * @summary returns a function that invokes the callback function after certain delay/timeout.
+ *
+ * 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
@@ -267,20 +267,18 @@ type CurriedArgs<TArgs extends unknown[], TArgsIsFinite extends boolean, TFunc e
  * @param	config.tid	   (optional) Timeout Id. If provided, will clear the timeout on first invocation.
  *
  * @example Debounce function calls
- * ```typescript
+ * ```javascript
  * import { deferred } from '@superutils/core'
  *
  * const handleChange = deferred(
- *     event => console.log(event.target.value),
+ *     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
+ * 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;
@@ -299,7 +297,13 @@ declare const deferred: {
 };
 
 /** Super for `deferred()` function */
-declare function debounce(...args: Parameters<typeof deferred>): (...args: unknown[]) => void;
+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
@@ -381,11 +385,6 @@ type IfPromiseAddValue<T> = T extends Promise<infer V> ? T | V : T;
  */
 declare const fallbackIfFails: <T, TArgs extends unknown[] = unknown[]>(target: T | ((...args: TArgs) => T), args: TArgs | (() => TArgs), fallbackValue: IfPromiseAddValue<T> | ((reason: unknown) => IfPromiseAddValue<T>)) => T;
 
-/** Cast a value as `any` type to bypass type check. Use with caution. */
-declare const asAny: <T = any>(x: unknown) => T;
-/** Force cast one type into another to bypass type checks. Use with caution. */
-declare const forceCast: <T>(x: unknown) => T;
-
 /** Check if value is an array */
 declare const isArr: <Item = unknown>(x: unknown) => x is Item[];
 /**
@@ -660,6 +659,19 @@ type ThrottleOptions<ThisArg = unknown> = {
  * @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;
@@ -1374,4 +1386,4 @@ declare const HASH_REGEX: RegExp;
  */
 declare const strToArr: (value: unknown, seperator?: string) => string[];
 
-export { type ArrayComparator, type AsyncFn, type CreateTuple, type CurriedArgs, type Curry, type DeferredOptions, type DropFirst, type DropFirstN, type DropLast, EMAIL_REGEX, type EntryComparator, type FindOptions, HASH_REGEX, HEX_REGEX, type IfPromiseAddValue, type IsFiniteTuple, type IsOptional, type IterableList, type KeepFirst, type KeepFirstN, type KeepOptionals, type KeepRequired, type MakeOptional, type MinLength, type NegativeNumber, type OptionalIf, type PositiveNumber, type PositiveNumberWithZero, type ReadOnlyAllowAddFn, ReadOnlyArrayHelper, type ReadOnlyConfig, type SearchOptions, type Slice, type SliceMapOptions, type SliceMapTransform, type SortOptions, type ThrottleOptions, type TimeoutId, type TupleMaxLength, type TupleWithAlt, type ValueOrFunc, type ValueOrPromise, arrReadOnly, arrReverse, arrToMap, arrUnique, asAny, clearClutter, copyToClipboard, curry, debounce, deferred, fallbackIfFails, filter, find, forceCast, getEntries, getKeys, getSize, getUrlParam, getValues, is, isArr, isArr2D, isArrLike, isArrLikeSafe, isArrObj, isArrUnique, isAsyncFn, isBool, isDate, isDateValid, isDefined, isEmpty, isEmptySafe, isEnvBrowser, isEnvNode, isEnvTouchable, isError, isFn, isInteger, isMap, isMapObj, isNumber, isObj, isPositiveInteger, isPositiveNumber, isPromise, isRegExp, isSet, isStr, isSymbol, isUint8Arr, isUrl, isUrlValid, mapJoin, 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, 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 };

package/dist/index.js

@@ -1,14 +1,9 @@
-// src/forceCast.ts
-var asAny = (x) => x;
-var forceCast = (x) => x;
-var forceCast_default = forceCast;
-
 // src/curry.ts
 function curry(func, ...[arity = func.length]) {
   const curriedFn = (...args) => {
     const _args = args;
-    if (_args.length >= arity) return func(...forceCast_default(args));
-    return (...nextArgs) => asAny(curriedFn)(
+    if (_args.length >= arity) return func(...args);
+    return (...nextArgs) => curriedFn(
       ..._args,
       ...nextArgs
     );
@@ -244,9 +239,7 @@ deferred.defaults = {
 var deferred_default = deferred;
 
 // src/debounce.ts
-function debounce(...args) {
-  return deferred_default(...args);
-}
+var debounce = deferred_default;
 
 // src/throttled.ts
 var throttled = (callback, delay = 50, config = {}) => {
@@ -346,7 +339,7 @@ var objCopy = (input, output, ignoreKeys, override = false, recursive = true) =>
     const value = input[key];
     const skip = _output.hasOwnProperty(key) && (override === "empty" ? !isEmpty(_output[key]) : isFn(override) ? !override(key, _output[key], value) : true);
     if (skip) continue;
-    const isPrimitive = [void 0, null, Infinity, NaN].includes(asAny(value)) || !isObj(value, false);
+    const isPrimitive = [void 0, null, Infinity, NaN].includes(value) || !isObj(value, false);
     if (isPrimitive) {
       _output[key] = value;
       continue;
@@ -356,26 +349,28 @@ var objCopy = (input, output, ignoreKeys, override = false, recursive = true) =>
         case Array.prototype:
           return clone(value, "[]");
         case ArrayBuffer.prototype:
-          return asAny(value).slice(0);
+          return value.slice(0);
         case Date.prototype:
-          return new Date(asAny(value).getTime());
+          return new Date(value.getTime());
         case Map.prototype:
           return new Map(
             clone(
-              Array.from(asAny(value)),
+              Array.from(
+                value
+              ),
               "[]"
             )
           );
         case RegExp.prototype:
-          return new RegExp(asAny(value));
+          return new RegExp(value);
         case Set.prototype:
           return new Set(
-            clone(Array.from(asAny(value)))
+            clone(Array.from(value))
           );
         case Uint8Array.prototype:
-          return new Uint8Array([...asAny(value)]);
+          return new Uint8Array([...value]);
         case URL.prototype:
-          return new URL(asAny(value));
+          return new URL(value);
         default:
           break;
       }
@@ -917,7 +912,6 @@ export {
   arrReverse,
   arrToMap,
   arrUnique,
-  asAny,
   clearClutter,
   copyToClipboard,
   curry,
@@ -926,7 +920,6 @@ export {
   fallbackIfFails,
   filter,
   find,
-  forceCast,
   getEntries,
   getKeys,
   getSize,

package/package.json

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