web-utils-kit 1.1.1 → 1.1.3

package/README.md

@@ -892,6 +892,30 @@ await res.json();
   <br/>
 </details>
 
+
+<details>
+  <summary><code>retryExternalRequest</code></summary>
+  <br/>
+
+  Executes an external request persistently, retrying on error with incremental delays defined in retryScheduleDuration (seconds).
+
+  ```typescript
+  import { retryExternalRequest } from 'web-utils-kit';
+
+  const res = await retryExternalRequest(
+    () => fetch('https://api.example.com/user/1'),
+    [404],
+    [3, 5],
+  );
+  await res.json();
+  // {
+  //   uid: '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d',
+  //   nickname: 'PythonWiz333'
+  // }
+  ```
+  <br/>
+</details>
+
 <br/>
 
 ## Types

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import type { IJSONValue, IUUIDVersion } from './shared/types.js';
 import { isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid } from './validations/index.js';
 import { type INumberFormatConfig, type IDateTemplate, type ITimeString, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, toMS, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON } from './transformers/index.js';
-import { type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction } from './utils/index.js';
-export { type IJSONValue, type IUUIDVersion, isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid, type INumberFormatConfig, type IDateTemplate, type ITimeString, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, toMS, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON, type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction, };
+import { type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction, retryExternalRequest } from './utils/index.js';
+export { type IJSONValue, type IUUIDVersion, isStringValid, isNumberValid, isIntegerValid, isTimestampValid, isObjectValid, isArrayValid, isEmailValid, isSlugValid, isPasswordValid, isOTPSecretValid, isOTPTokenValid, isJWTValid, isAuthorizationHeaderValid, isSemverValid, isURLValid, isUUIDValid, type INumberFormatConfig, type IDateTemplate, type ITimeString, prettifyNumber, prettifyDate, prettifyFileSize, prettifyBadgeCount, capitalizeFirst, toTitleCase, toSlug, truncateText, maskMiddle, applySubstitutions, toMS, stringifyJSON, stringifyJSONDeterministically, parseJSON, createDeepClone, pruneJSON, type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, pickProps, omitProps, filterByQuery, delay, retryAsyncFunction, retryExternalRequest, };

package/dist/index.js

@@ -1 +1 @@
-import{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid}from"./validations/index.js";import{prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON}from"./transformers/index.js";import{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction}from"./utils/index.js";export{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid,prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON,generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction};
+import{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid}from"./validations/index.js";import{prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON}from"./transformers/index.js";import{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction,retryExternalRequest}from"./utils/index.js";export{isStringValid,isNumberValid,isIntegerValid,isTimestampValid,isObjectValid,isArrayValid,isEmailValid,isSlugValid,isPasswordValid,isOTPSecretValid,isOTPTokenValid,isJWTValid,isAuthorizationHeaderValid,isSemverValid,isURLValid,isUUIDValid,prettifyNumber,prettifyDate,prettifyFileSize,prettifyBadgeCount,capitalizeFirst,toTitleCase,toSlug,truncateText,maskMiddle,applySubstitutions,toMS,stringifyJSON,stringifyJSONDeterministically,parseJSON,createDeepClone,pruneJSON,generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,pickProps,omitProps,filterByQuery,delay,retryAsyncFunction,retryExternalRequest};

package/dist/utils/index.d.ts

@@ -121,9 +121,18 @@ declare const delay: (seconds: number) => Promise<void>;
 /**
  * Executes an asynchronous function persistently, retrying on error with incremental delays
  * defined in retryScheduleDuration (seconds).
- * @param func The asynchronous function to be executed persistently.
+ * @param fn The asynchronous function to be executed persistently.
  * @param retryScheduleDuration? An array of numbers representing the delay (in seconds) between each retry attempt. Defaults to [3, 5].
  * @returns A promise that resolves with the result of the asynchronous function or rejects with the last encountered error.
  */
-declare const retryAsyncFunction: <T>(func: () => Promise<T>, retryScheduleDuration?: number[]) => Promise<T>;
+declare const retryAsyncFunction: <T>(fn: () => Promise<T>, retryScheduleDuration?: number[]) => Promise<T>;
+/**
+ * Executes an external request persistently, retrying on error with incremental delays
+ * defined in retryScheduleDuration (seconds).
+ * @param fn The asynchronous function representing the external request.
+ * @param nonRetryiableCodes? An array of HTTP status codes that should not be retried. (Defaults to [401, 403, 404, 409, 429])
+ * @param retryScheduleDuration? The schedule of delays (in seconds) between retries. (Defaults to [3, 5])
+ * @returns A promise that resolves to the result of the asynchronous function.
+ */
+export declare const retryExternalRequest: <T>(fn: () => Promise<T>, nonRetryiableCodes?: number[], retryScheduleDuration?: number[]) => Promise<T>;
 export { type ISortDirection, type IFilterByQueryOptions, generateUUID, generateRandomString, generateRandomFloat, generateRandomInteger, generateSequence, sortPrimitives, sortRecords, shuffleArray, splitArrayIntoBatches, pickProps, omitProps, isEqual, filterByQuery, delay, retryAsyncFunction, };

package/dist/utils/index.js

@@ -1 +1 @@
-import{v4 as uuidv4,v7 as uuidv7}from"uuid";import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isIntegerValid}from"../validations/index.js";import{stringifyJSONDeterministically}from"../transformers/index.js";import{canArrayBeShuffled,validateObjectAndKeys}from"./validations.js";import{buildNormalizedQueryTokens}from"./transformers.js";import{filterItemsByQueryTokens}from"./utils.js";const generateUUID=e=>7===e?uuidv7():uuidv4(),generateRandomString=(e,r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")=>{let t="",n=0;for(;n<e;)t+=r.charAt(Math.floor(Math.random()*r.length)),n+=1;return t},generateRandomFloat=(e,r)=>{const t=Math.random()*(r-e+1)+e;return t>r?r:t},generateRandomInteger=(e,r)=>Math.floor(generateRandomFloat(e,r)),generateSequence=(e,r,t=1)=>Array.from({length:(r-e)/t+1},((r,n)=>e+n*t)),__sortStringValues=(e,r,t)=>{const n=e.toLocaleLowerCase(),o=r.toLocaleLowerCase();return n>o?"asc"===t?1:-1:o>n?"asc"===t?-1:1:0},__sortNumberValues=(e,r,t)=>"asc"===t?e-r:r-e,sortPrimitives=e=>(r,t)=>{if("string"==typeof r&&"string"==typeof t)return __sortStringValues(r,t,e);if("number"==typeof r&&"number"==typeof t)return __sortNumberValues(r,t,e);throw new Error(encodeError(`Unable to sort list of primitive values as they can only be string | number and must not be mixed. Received: ${typeof r}, ${typeof t}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},sortRecords=(e,r)=>(t,n)=>{if("string"==typeof t[e]&&"string"==typeof n[e])return __sortStringValues(t[e],n[e],r);if("number"==typeof t[e]&&"number"==typeof n[e])return __sortNumberValues(t[e],n[e],r);throw new Error(encodeError(`Unable to sort list of record values as they can only be string | number and must not be mixed. Received: ${typeof t[e]}, ${typeof n[e]}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},shuffleArray=e=>{canArrayBeShuffled(e);const r=e.slice();for(let e=r.length-1;e>0;e-=1){const t=Math.floor(Math.random()*(e+1));[r[e],r[t]]=[r[t],r[e]]}return r},splitArrayIntoBatches=(e,r)=>{if(!e.length)return[];if(!isIntegerValid(r,1))throw new Error(encodeError(`In order to split an array into batches, the batch size must be an integer greater than 0. Received: ${r}`,ERRORS.INVALID_BATCH_SIZE));const t=[];for(let n=0;n<e.length;n+=r)t.push(e.slice(n,n+r));return t},pickProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(r.map((r=>[r,e[r]])))),omitProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(Object.entries(e).filter((([e])=>!r.includes(e))))),isEqual=(e,r)=>stringifyJSONDeterministically(e)===stringifyJSONDeterministically(r),filterByQuery=(e,r,t)=>{if(!e.length||!r)return e;const n=buildNormalizedQueryTokens(r);if(!n.length)return e;const o=filterItemsByQueryTokens(e,n,t?.queryProp);return"number"==typeof t?.limit?o.slice(0,t.limit):o},delay=e=>new Promise((r=>{setTimeout(r,Math.round(1e3*e))})),retryAsyncFunction=async(e,r=[3,5])=>{try{return await e()}catch(t){if(0===r.length)throw t;return await delay(r[0]),retryAsyncFunction(e,r.slice(1))}};export{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,splitArrayIntoBatches,pickProps,omitProps,isEqual,filterByQuery,delay,retryAsyncFunction};
+import{v4 as uuidv4,v7 as uuidv7}from"uuid";import{encodeError}from"error-message-utils";import{ERRORS}from"../shared/errors.js";import{isIntegerValid,isObjectValid}from"../validations/index.js";import{stringifyJSONDeterministically}from"../transformers/index.js";import{canArrayBeShuffled,validateObjectAndKeys}from"./validations.js";import{buildNormalizedQueryTokens}from"./transformers.js";import{filterItemsByQueryTokens}from"./utils.js";const generateUUID=e=>7===e?uuidv7():uuidv4(),generateRandomString=(e,r="ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789")=>{let t="",n=0;for(;n<e;)t+=r.charAt(Math.floor(Math.random()*r.length)),n+=1;return t},generateRandomFloat=(e,r)=>{const t=Math.random()*(r-e+1)+e;return t>r?r:t},generateRandomInteger=(e,r)=>Math.floor(generateRandomFloat(e,r)),generateSequence=(e,r,t=1)=>Array.from({length:(r-e)/t+1},((r,n)=>e+n*t)),__sortStringValues=(e,r,t)=>{const n=e.toLocaleLowerCase(),o=r.toLocaleLowerCase();return n>o?"asc"===t?1:-1:o>n?"asc"===t?-1:1:0},__sortNumberValues=(e,r,t)=>"asc"===t?e-r:r-e,sortPrimitives=e=>(r,t)=>{if("string"==typeof r&&"string"==typeof t)return __sortStringValues(r,t,e);if("number"==typeof r&&"number"==typeof t)return __sortNumberValues(r,t,e);throw new Error(encodeError(`Unable to sort list of primitive values as they can only be string | number and must not be mixed. Received: ${typeof r}, ${typeof t}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},sortRecords=(e,r)=>(t,n)=>{if("string"==typeof t[e]&&"string"==typeof n[e])return __sortStringValues(t[e],n[e],r);if("number"==typeof t[e]&&"number"==typeof n[e])return __sortNumberValues(t[e],n[e],r);throw new Error(encodeError(`Unable to sort list of record values as they can only be string | number and must not be mixed. Received: ${typeof t[e]}, ${typeof n[e]}`,ERRORS.MIXED_OR_UNSUPPORTED_DATA_TYPES))},shuffleArray=e=>{canArrayBeShuffled(e);const r=e.slice();for(let e=r.length-1;e>0;e-=1){const t=Math.floor(Math.random()*(e+1));[r[e],r[t]]=[r[t],r[e]]}return r},splitArrayIntoBatches=(e,r)=>{if(!e.length)return[];if(!isIntegerValid(r,1))throw new Error(encodeError(`In order to split an array into batches, the batch size must be an integer greater than 0. Received: ${r}`,ERRORS.INVALID_BATCH_SIZE));const t=[];for(let n=0;n<e.length;n+=r)t.push(e.slice(n,n+r));return t},pickProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(r.map((r=>[r,e[r]])))),omitProps=(e,r)=>(validateObjectAndKeys(e,r),Object.fromEntries(Object.entries(e).filter((([e])=>!r.includes(e))))),isEqual=(e,r)=>stringifyJSONDeterministically(e)===stringifyJSONDeterministically(r),filterByQuery=(e,r,t)=>{if(!e.length||!r)return e;const n=buildNormalizedQueryTokens(r);if(!n.length)return e;const o=filterItemsByQueryTokens(e,n,t?.queryProp);return"number"==typeof t?.limit?o.slice(0,t.limit):o},delay=e=>new Promise((r=>{setTimeout(r,Math.round(1e3*e))})),retryAsyncFunction=async(e,r=[3,5])=>{try{return await e()}catch(t){if(0===r.length)throw t;return await delay(r[0]),retryAsyncFunction(e,r.slice(1))}};export const retryExternalRequest=async(e,r=[401,403,404,409,429],t=[3,5])=>{try{return await e()}catch(n){if(0===t.length||isObjectValid(n)&&n.statusCode&&r.includes(n.statusCode))throw n;return await delay(t[0]),retryExternalRequest(e,r,t.slice(1))}};export{generateUUID,generateRandomString,generateRandomFloat,generateRandomInteger,generateSequence,sortPrimitives,sortRecords,shuffleArray,splitArrayIntoBatches,pickProps,omitProps,isEqual,filterByQuery,delay,retryAsyncFunction};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-utils-kit",
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "The web-utils-kit package provides a collection of well-tested and thoroughly documented utility functions for various web development needs. Each function adheres to a strict coding style and best practices to ensure consistency and maintainability.",
   "type": "module",
   "main": "dist/index.js",